eco-helpers 3.2.19 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e64f4c0a2c6dc0b63299469ad23910bd227a3a8aa95f040f8cf0c9019baeccea
-  data.tar.gz: d34e7ef09189ef29233f81263399f5af0b2fb36fdb86365427449c9da9c75fef
+  metadata.gz: 2c1f4723827d6dabfa094fd943b573a00bfe19c6d16b4ea0cb528c01d23d74d0
+  data.tar.gz: 6cb1e6109c1d4150f2a52c0359941b02be893065cc6b732932af117ad6bbd08c
 SHA512:
-  metadata.gz: f334bce839ff57df6dedcd64891bc2b4ddb230419d617746e8c65ab4033ca7df2d65c5b0716aa823b43625138a2f9e829a060cabba4f71b02a444661e72652e1
-  data.tar.gz: 047b80c9620899819844f1e2822fe991487b41b0f05b440836fbbccfda8a190b0f9da2ee8a19841852fe7e3ef3d15edb600c81aac5c350341e52e715ad926f3b
+  metadata.gz: 515a129e3e75c42d0c16de5154a0e06e7d5854b65e766cf7e144b7097b6e55f2d2db5130ee05828f3c672da57f443517198816df18523ff952aefd8d93f9a645
+  data.tar.gz: aa5c685e34346dfe3bc41c006c89790eba83470327d950eeb531b0416b14228616d8cee57ba6d9f82d351db5ef3d4d6aa6a45aa147c6702821a1454a730fe879

data/CHANGELOG.md

@@ -2,6 +2,95 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.3.0] - 2026-08-13
+
+Adopts **`ecoportal-api-graphql` 2.0.0** (published 2026-08-13): floor raised from
+`~> 1.3, >= 1.3.14` to `~> 2.0, >= 2.0.0`. Minor rather than major here — 2.0.0's breaking set
+removed surfaces that either targeted mutations the live schema never had or were dead accessors,
+and a sweep of this repo finds **no consumer of any of them** (`editPage`,
+`editPageCreatorPermissions`, the AI-summary mutations, the SmartFill pair — zero hits outside
+this repo's own readiness notes). Nothing in `lib/` changes behaviour as a result of the bump.
+
+★ **What starts WORKING, which matters more here than what broke.** Several paths were sending
+documents the schema rejected, so they always errored; on 2.0.0 they really write. For this gem
+the one to watch is the **`OozeRedirect` force path** — malformed `executeWorkflowCommands` until
+graphql 1.3.15 fixed it, so its behaviour flips from "always errored" to "really writes" with no
+signature change to warn anyone. **Re-verify it on a sandbox org before trusting it in a customer
+run.** Also newly live via the gem: the page-level `executeWorkflowCommands` bus, File-field
+attach writes, `updatePresetView` column edits, viewable-field management and Date-field renewals.
+
+Consumers pinned to `~> 3.2` do not pick this up automatically, so adopting graphql 2.0.0 stays a
+deliberate per-repo decision.
+
+★ **The published gem is now `lib/` only.** `spec.files` excluded just `test|spec|features`, so
+every top-level directory added since shipped by default — `.ai-assistance/` internal notes,
+`docs/` (including the rolling worklog) and `.claude/`. `spec.files` is now an allowlist
+(`lib/`, `exe/`, README, LICENSE, CHANGELOG). All `lib/` files are unchanged; nothing outside
+`lib/` was ever loaded at runtime. Same fix as `ecoportal-api-graphql` 2.0.0.
+
+## [3.2.20] - 2026-08-11
+
+Reunites the released `3.2.19` hotfix line with `master`. `3.2.19` was cut from the `v3.2.18` tag
+and **never merged back**, so two halves were split across branches: `master` carried
+`Eco::API::Custom::Cli` (unreleased since 2026-07-25, and the reason `mns/config/cli.rb` could not
+load on any published gem) while `3.2.19` carried the ooze KPI counter fix and the graphql floor.
+This release carries both. Dependency floors are the max of each side.
+
+### Native GraphQL activity/dashboard readers + contractor manager-settings write
+
+Additive, all **NATIVE** (no `Compat::` layer). Depends on the `ecoportal-api-graphql`
+`feat/graphql-activity-logs` branch (polymorphic `activityLogs` / `page.activities` models);
+during development it is wired via a temporary Gemfile `path:` override that a gem version bump
+replaces on release.
+
+### Changed
+
+- `ecoportal-api` dependency floor raised to `0.10.17`: inherits the `WithRetry` fix making
+  `HTTP::TimeoutError` retryable (transient timeouts no longer kill batch loops).
+
+### Added
+
+- **Shared connection-reader substrate** — `Helpers::Base::ConnectionReader`: an `Enumerable`
+  mixin that wraps the gem's lazy `QueryConnection#each` (cursor pagination over
+  `pageInfo.endCursor`/`hasNextPage`) behind a uniform `each` / `to_a(limit:)` / `page_size`
+  surface. All new readers build on it.
+- **System Access Logs reader** — `Helpers::AccessLogs::Base#access_logs` over
+  `currentOrganization.activityLogs`, exposing the full filter set (user_ids, resource_ids,
+  filter_superusers, activity_type, resource_type, source, date_filter) → yields `Model::ActivityLog`.
+- **Page history reader** — `Helpers::Pages::Activities#page_activities` over `page(id:).activities`
+  (page id + `sorters:`/`search_conf:` + lazy pagination) → yields `Model::Activity`.
+- **Dashboards reader** — `Helpers::Dashboards::Base#dashboards` over `dashboardSearch` → yields
+  `Model::MinimalDashboard`.
+- **Contractor manager-settings WRITE** — `Helpers::Contractors::Base::ManagerSettings#update_contractor_manager_settings`
+  (also exposed via `Samples::Contractors::DSL#update_manager_settings`), driving the gem's
+  `Builder::ContractorEntity#update_manager_settings`. Guarded: **dry-run/simulate** short-circuits
+  before any mutation (returns the intended input); **-no-email** discipline honoured
+  (`options.workflow.no_email` or explicit `no_email:` suppresses the helper's own notification).
+- **Thin live drivers** under `tests/` (read-only for the three readers; dry-run-only for the
+  contractor write) plus a shared `tests/env_graphql.rb` harness.
+- Offline specs for all of the above (23 examples).
+- `Eco::API::Common::Loaders::CliConfig` exposed via `Eco::API::Custom::Cli`.
+
+### Fixed
+
+- **`Template::Base` could never run — `CommandEmitter` was unresolvable.** The class was declared
+  with the compact `class Template::Base` form inside `module ...::Pages`, which leaves `Template`
+  out of the file's lexical scope, so the bare `CommandEmitter` reference in `#desired_commands`
+  raised `NameError` on every call — meaning every build-from-scratch template use case failed
+  before emitting a single command. Now nested as `module Template` + `class Base`, matching the
+  sibling files (`command_emitter.rb`, `csv_build/builder.rb`) whose bare cross-references already
+  worked for exactly that reason. Public constant path is unchanged. Found by the first spec ever
+  written against this class.
+
+- **Ooze update KPI counters now count GraphQL updates.** `RegisterUpdateCase` tallied
+  `updated`/`failed` only when the result `is_a?(Ecoportal::API::Common::Response)`, but the
+  GraphQL compat layer returns an `Ecoportal::API::GraphQL::Compat::Response` (duck-types
+  `success?`/`status`, not in that class hierarchy) — so GraphQL updates were silently
+  uncounted (`Updated 0 (attempted: N)`, `Failed 0`) even when the write applied. Guard is now
+  `respond_to?(:success?)`; `false`/`nil` (dry-run / no-op) still skip. Inherited by
+  `TargetOozesUpdateCase` → TOOCS / cans-upsert. Also shipped as the maintenance release
+  `3.2.19` off `v3.2.18`; regression spec added.
+
 ## [3.2.19] - 2026-07-16
 
 Farmers / `cans-upsert` reliability adoption + an ooze KPI counter fix. **Backwards-compatible.**

data/lib/eco/api/common/session/base_session.rb

@@ -36,6 +36,10 @@ module Eco::API::Common::Session
       enviro.api?(version: version)
     end
 
+    def missing_api_params(version: nil)
+      enviro.missing_api_params(version: version)
+    end
+
     def file_manager
       enviro.file_manager
     end

data/lib/eco/api/common/session/environment.rb

@@ -63,6 +63,11 @@ module Eco::API::Common::Session
       config.apis.active_api.version_available?(version)
     end
 
+    # @return [Array<Symbol>] required parameters for `version` that are missing.
+    def missing_api_params(version:)
+      config.apis.active_api.missing_api_params(version)
+    end
+
     # Shortcut to logger.
     def log(level, &block)
       return unless logger.respond_to?(:level)

data/lib/eco/api/custom/cli.rb

@@ -0,0 +1,3 @@
+# Helper class to create a custom `Cli` config
+class Eco::API::Custom::Cli < Eco::API::Common::Loaders::CliConfig
+end

data/lib/eco/api/session/config/api.rb

@@ -104,8 +104,10 @@ module Eco
             return current if current && !switch_logger
 
             unless api_params?(version)
+              missing = missing_api_params(version)
               msg  = "The api configuration for #{description} "
-              msg << "is missing data for the api version '#{self.version(version)}'"
+              msg << "is missing data for the api version '#{self.version(version)}': "
+              msg << "missing params #{missing.map {|param| ":#{param}"}.join(', ')}"
               raise ArgumentError, msg
             end
 
@@ -196,6 +198,12 @@ module Eco
             api_params?(version)
           end
 
+          # @return [Array<Symbol>] the required parameters for `version` that are
+          #   currently missing (empty when all of them are present).
+          def missing_api_params(version)
+            required_api_params(version).reject {|_param, value| value}.keys
+          end
+
           def version(value = nil)
             self.class.to_version(value || self['version'])
           end
@@ -224,15 +232,18 @@ module Eco
             when :v2
               klass.new(user_key: user_key, org_key: external_key, host: host, logger: logger)
             when :graphql
-              kargs = {
-                host:   host,
-                org_id: org_id,
-                email:  email,
-                pass:   pass
-              }
-
-              kargs.merge!({no_schema: true}) if ENV['GRAPHQL_FETCH_SCHEMA'] == "false"
-              klass.new(**kargs)
+              # NOTE: `GRAPHQL_FETCH_SCHEMA` is a documented no-op. `Ecoportal::API::GraphQL#initialize`
+              # (email:, pass:, org_id:, host:, api_key:) has never accepted a `no_schema:` keyword —
+              # it always builds its internal client with `no_schema: true` and has no public way to
+              # turn schema introspection on. Passing the unknown keyword raised ArgumentError, so the
+              # flag was worse than a no-op: setting `GRAPHQL_FETCH_SCHEMA=false` crashed api() instead
+              # of skipping a fetch that the gem's public API never performs regardless.
+              if ENV['GRAPHQL_FETCH_SCHEMA'] == "false"
+                warn "[eco-helpers] GRAPHQL_FETCH_SCHEMA is a no-op: " \
+                     "Ecoportal::API::GraphQL never fetches the schema (no_schema: true, hardcoded)."
+              end
+
+              klass.new(host: host, org_id: org_id, email: email, pass: pass)
             end.tap do |api|
               next unless api
               next if log_connection? # prevent over-logging
@@ -248,15 +259,23 @@ module Eco
 
           # Checks if the necessary parameters for a specific `API` version are available.
           def api_params?(version)
+            missing_api_params(version).empty?
+          end
+
+          # Required parameters (as `name => value` pairs) for a specific `API` version.
+          # @note `to_version` always normalises to one of the known versions below.
+          def required_api_params(version)
             case self.class.to_version(version)
             when :v0
-              internal_key && host
+              {internal_key: internal_key, host: host}
             when :v1
-              external_key && host
+              {external_key: external_key, host: host}
             when :v2
-              external_key && user_key && host
+              {external_key: external_key, user_key: user_key, host: host}
             when :graphql
-              email && pass && org_id && host
+              {email: email, pass: pass, org_id: org_id, host: host}
+            else
+              {}
             end
           end
 

data/lib/eco/api/usecases/graphql/helpers/access_logs/base/reader.rb

@@ -0,0 +1,59 @@
+module Eco::API::UseCases::GraphQL::Helpers::AccessLogs
+  module Base
+    # NATIVE reader over `currentOrganization.activityLogs` (the ActivityLogUnion behind the web
+    # "System Access Logs" page). Lazily paginates and yields `Model::ActivityLog` records.
+    #
+    # Exposes the full server filter set. Construct via `Helpers::AccessLogs::Base#access_logs`:
+    #   access_logs(source: 'web', resource_type: 'view_dashboard').each { |log| ... }
+    #   access_logs(date_filter: { from: from_iso, to: to_iso }).to_a(limit: 500)
+    class Reader
+      include Eco::API::UseCases::GraphQL::Helpers::Base::ConnectionReader
+
+      # @param graphql [Ecoportal::API::GraphQL] the active gem client.
+      # @param user_ids [Array<String>, nil]
+      # @param resource_ids [Array<String>, nil]
+      # @param filter_superusers [Boolean, nil]
+      # @param activity_type [String, nil] free-text activity type filter.
+      # @param resource_type [String, nil] ActivityLogTypesEnum value (e.g. 'view_dashboard').
+      # @param source [String, nil] SourceEnum value (e.g. 'web', 'api').
+      # @param date_filter [Hash, nil] `{ from:, to: }` (ISO8601), maps to DateRange.
+      def initialize(
+        graphql,
+        user_ids:          nil,
+        resource_ids:      nil,
+        filter_superusers: nil,
+        activity_type:     nil,
+        resource_type:     nil,
+        source:            nil,
+        date_filter:       nil
+      )
+        @graphql           = graphql
+        @user_ids          = user_ids
+        @resource_ids      = resource_ids
+        @filter_superusers = filter_superusers
+        @activity_type     = activity_type
+        @resource_type     = resource_type
+        @source            = source
+        @date_filter       = date_filter
+      end
+
+      private
+
+      def connection_query
+        @graphql.currentOrganization.activityLogs
+      end
+
+      def reader_params
+        {
+          userIds:          @user_ids,
+          resourceIds:      @resource_ids,
+          filterSuperusers: @filter_superusers,
+          activityType:     @activity_type,
+          resourceType:     @resource_type,
+          source:           @source,
+          dateFilter:       @date_filter
+        }
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/access_logs/base.rb

@@ -0,0 +1,17 @@
+require_relative 'base/reader'
+
+module Eco::API::UseCases::GraphQL::Helpers::AccessLogs
+  # System Access Logs helper mixin — NATIVE reader over `activityLogs`.
+  module Base
+    include Eco::API::UseCases::GraphQL::Helpers::Base
+
+    private
+
+    # Build a lazy reader over the org's system access logs (ActivityLogUnion).
+    # @see Reader#initialize for the supported filters.
+    # @return [Reader]
+    def access_logs(**filters)
+      Reader.new(graphql, **filters)
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/access_logs.rb

@@ -0,0 +1,7 @@
+module Eco::API::UseCases::GraphQL::Helpers
+  # NATIVE System Access Logs readers (currentOrganization.activityLogs).
+  module AccessLogs
+  end
+end
+
+require_relative 'access_logs/base'

data/lib/eco/api/usecases/graphql/helpers/base/connection_reader.rb

@@ -0,0 +1,70 @@
+module Eco::API::UseCases::GraphQL::Helpers::Base
+  # Shared substrate for NATIVE GraphQL connection readers.
+  #
+  # The gem's `Logic::QueryConnection` is already `Enumerable` and paginates lazily over
+  # `first`/`after` using `pageInfo.endCursor`/`hasNextPage` (see its `#each`). This mixin wraps
+  # that machinery behind a small, uniform reader surface so every native reader (access logs,
+  # page activities, dashboards, ...) exposes the same `each` / `to_a` / `first(n)` behaviour and
+  # a consistent `page_size` without re-implementing cursor pagination.
+  #
+  # A concrete reader supplies a `#query` (a gem query object, e.g.
+  # `graphql.currentOrganization.activityLogs`) and the per-call filter/argument hash via
+  # `#reader_params`. Everything else (lazy iteration, batching, materialising) is inherited.
+  module ConnectionReader
+    include Enumerable
+
+    # Default number of nodes fetched per network round-trip.
+    DEFAULT_PAGE_SIZE = 100
+
+    # Iterate over every node across all pages (lazy — one network page at a time).
+    # @yieldparam node [Object] a gem read model (e.g. Model::ActivityLog / Model::Activity).
+    # @return [Enumerator] when no block is given.
+    def each(&block)
+      return to_enum(:each) unless block
+
+      connection_query.each(**each_params, &block)
+    end
+
+    # Materialise a bounded number of nodes without draining the whole connection.
+    # @param limit [Integer, nil] maximum nodes to return; nil = all pages.
+    # @return [Array]
+    def to_a(limit: nil)
+      return super() if limit.nil?
+
+      take(limit)
+    end
+
+    # @return [Integer] nodes fetched per page.
+    def page_size
+      @page_size ||= DEFAULT_PAGE_SIZE
+    end
+
+    # @param size [Integer]
+    def page_size=(size)
+      @page_size = Integer(size)
+    end
+
+    private
+
+    # The gem query object to iterate (must respond to `#each(**kargs)` — i.e. a
+    # `Logic::QueryConnection`). Concrete readers MUST override.
+    # @return [Ecoportal::API::GraphQL::Logic::QueryConnection]
+    def connection_query
+      raise NotImplementedError, "#{self.class} must implement #connection_query"
+    end
+
+    # Per-call arguments (filters + page id + ...) merged into every page request.
+    # Concrete readers override to add their own filters. `first` defaults to `page_size`.
+    # @return [Hash]
+    def reader_params
+      {}
+    end
+
+    # Final kargs handed to the gem's `QueryConnection#each` — reader_params with a
+    # default `first`, and nils stripped so unset filters are not sent.
+    # @return [Hash]
+    def each_params
+      { first: page_size }.merge(reader_params).compact
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/base/graphql_env.rb

@@ -6,8 +6,12 @@ module Eco::API::UseCases::GraphQL::Helpers::Base
     private
 
     def graphql
-      msg = "The credentials or basic graphql config are missing for the active environment"
-      raise msg unless session.api?(version: :graphql)
+      unless session.api?(version: :graphql)
+        missing = session.missing_api_params(version: :graphql)
+        msg  = "The credentials or basic graphql config are missing for the active environment"
+        msg << " (missing params: #{missing.map {|param| ":#{param}"}.join(', ')})" if missing.any?
+        raise msg
+      end
 
       @graphql ||= session.api(version: :graphql)
     end

data/lib/eco/api/usecases/graphql/helpers/base.rb

@@ -3,6 +3,7 @@ module Eco::API::UseCases::GraphQL::Helpers
     require_relative 'base/error_handling'
     require_relative 'base/case_env'
     require_relative 'base/graphql_env'
+    require_relative 'base/connection_reader'
 
     include CaseEnv
     include GraphQLEnv

data/lib/eco/api/usecases/graphql/helpers/contractors/base/manager_settings.rb

@@ -0,0 +1,64 @@
+module Eco::API::UseCases::GraphQL::Helpers::Contractors
+  module Base
+    # NATIVE contractor **write** helper — `updateContractorManagerSettings`.
+    #
+    # Drives the gem's `Builder::ContractorEntity#update_manager_settings` to set the
+    # organisation's contractor-manager auto-approval settings and whether contractor admins
+    # may add other admins.
+    #
+    # Guards (aligned with the repo's write discipline):
+    # - **dry-run / simulate:** when `simulate?` (or `dry_run:` is passed), NO mutation is sent;
+    #   the intended input is logged and returned so callers can inspect it.
+    # - **-no-email:** honoured — when email is suppressed (`options.dig(:workflow, :no_email)`
+    #   or an explicit `no_email:`), the helper does not emit its own success notification. The
+    #   server-side mutation itself sends no member email for this settings change.
+    module ManagerSettings
+      include Eco::API::UseCases::GraphQL::Helpers::Base
+
+      private
+
+      # Update the org's contractor manager settings.
+      # @param cm_auto_approvals_settings [Hash, nil] AutoApprovalsInput
+      #   ({ enabled:, approvalConditions: }). Required by the schema for a real update.
+      # @param allow_contractor_admins_to_add_admins [Boolean, nil]
+      # @param dry_run [Boolean, nil] force simulate for this call (in addition to `simulate?`).
+      # @param no_email [Boolean, nil] suppress this helper's own notification for this call.
+      # @return [Hash] when simulated: the intended input hash. Otherwise: the mutation payload.
+      def update_contractor_manager_settings(
+        cm_auto_approvals_settings:            nil,
+        allow_contractor_admins_to_add_admins: nil,
+        dry_run:                               nil,
+        no_email:                              nil
+      )
+        input = {}
+        input[:cmAutoApprovalsSettings] = cm_auto_approvals_settings unless cm_auto_approvals_settings.nil?
+        unless allow_contractor_admins_to_add_admins.nil?
+          input[:allowContractorAdminsToAddAdmins] =
+            allow_contractor_admins_to_add_admins
+        end
+
+        if dry_run || simulate?
+          log(:info) { "[dry-run] updateContractorManagerSettings input: #{input}" }
+          return input
+        end
+
+        graphql.contractorEntity.update_manager_settings(input: input).tap do
+          notify_manager_settings_updated(input) unless suppress_email?(no_email)
+        end
+      end
+
+      # @return [Boolean] whether this helper's own notification email is suppressed.
+      def suppress_email?(no_email)
+        return true if no_email
+        return true if respond_to?(:options, true) && options.dig(:workflow, :no_email)
+
+        false
+      end
+
+      # Hook for a success notification (kept minimal; overridable). Logs by default.
+      def notify_manager_settings_updated(input)
+        log(:info) { "Updated contractor manager settings: #{input}" }
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/contractors/base.rb

@@ -1,8 +1,10 @@
 require_relative 'base/load'
+require_relative 'base/manager_settings'
 
 module Eco::API::UseCases::GraphQL::Helpers::Contractors
   module Base
     include Eco::API::UseCases::GraphQL::Helpers::Base
     include Load
+    include ManagerSettings
   end
 end

data/lib/eco/api/usecases/graphql/helpers/dashboards/base/reader.rb

@@ -0,0 +1,30 @@
+module Eco::API::UseCases::GraphQL::Helpers::Dashboards
+  module Base
+    # NATIVE reader over `currentOrganization.dashboardSearch` (MinimalDashboardConnection).
+    # Lazily paginates and yields `Model::MinimalDashboard` records.
+    #
+    # Use via `Helpers::Dashboards::Base#dashboards`:
+    #   dashboards(query: 'safety').each { |d| ... }
+    #   dashboards.to_a
+    class Reader
+      include Eco::API::UseCases::GraphQL::Helpers::Base::ConnectionReader
+
+      # @param graphql [Ecoportal::API::GraphQL] the active gem client.
+      # @param search_conf [Hash, nil] a `Search` input hash ({ query:, filters:, sorters: }).
+      def initialize(graphql, search_conf: nil)
+        @graphql     = graphql
+        @search_conf = search_conf
+      end
+
+      private
+
+      def connection_query
+        @graphql.currentOrganization.dashboardSearch
+      end
+
+      def reader_params
+        { searchConf: @search_conf }
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/dashboards/base.rb

@@ -0,0 +1,20 @@
+require_relative 'base/reader'
+
+module Eco::API::UseCases::GraphQL::Helpers::Dashboards
+  # Dashboards helper mixin — NATIVE reader over `dashboardSearch`.
+  module Base
+    include Eco::API::UseCases::GraphQL::Helpers::Base
+
+    private
+
+    # Build a lazy reader over the org's dashboards (MinimalDashboardConnection).
+    # @param query [String, nil] free-text search shorthand (→ search_conf { query: }).
+    # @param search_conf [Hash, nil] full Search input (takes precedence over `query`).
+    # @return [Reader]
+    def dashboards(query: nil, search_conf: nil)
+      conf = search_conf
+      conf ||= { query: query } if query
+      Reader.new(graphql, search_conf: conf)
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/dashboards.rb

@@ -0,0 +1,7 @@
+module Eco::API::UseCases::GraphQL::Helpers
+  # NATIVE dashboard readers (currentOrganization.dashboardSearch).
+  module Dashboards
+  end
+end
+
+require_relative 'dashboards/base'

data/lib/eco/api/usecases/graphql/helpers/pages/activities.rb

@@ -0,0 +1,51 @@
+module Eco::API::UseCases::GraphQL::Helpers::Pages
+  # NATIVE reader over `page(id:).activities` (the ActivityInterface behind a page's history /
+  # changelog feed). Lazily paginates and yields `Model::Activity` records.
+  #
+  # Use via `Helpers::Pages::Activities#page_activities`:
+  #   page_activities(page_id).each { |a| ... }
+  #   page_activities(page_id, sorters: [{ key: 'updated_at', direction: 'desc' }]).to_a(limit: 50)
+  module Activities
+    # Lazy activity-feed reader for a single page.
+    class Reader
+      include Eco::API::UseCases::GraphQL::Helpers::Base::ConnectionReader
+
+      # @param graphql [Ecoportal::API::GraphQL] the active gem client.
+      # @param page_id [String] the page id whose activities to read.
+      # @param search_conf [Hash, nil] a `Search` input hash (typically `{ sorters: [...] }`).
+      #   Defaults to the web feature's ordering: newest updates first.
+      def initialize(graphql, page_id, search_conf: nil)
+        @graphql     = graphql
+        @page_id     = page_id
+        @search_conf = search_conf || DEFAULT_SEARCH_CONF
+      end
+
+      DEFAULT_SEARCH_CONF = { sorters: [{ direction: 'desc', key: 'updated_at' }] }.freeze
+
+      private
+
+      def connection_query
+        @graphql.currentOrganization.pageActivities
+      end
+
+      def reader_params
+        { id: @page_id, searchConf: @search_conf }
+      end
+    end
+
+    include Eco::API::UseCases::GraphQL::Helpers::Base
+
+    private
+
+    # Build a lazy reader over a page's activity/history feed.
+    # @param page_id [String]
+    # @param sorters [Array<Hash>, nil] shorthand for `search_conf: { sorters: ... }`.
+    # @param search_conf [Hash, nil] full Search input (takes precedence over `sorters`).
+    # @return [Reader]
+    def page_activities(page_id, sorters: nil, search_conf: nil)
+      conf = search_conf
+      conf ||= { sorters: sorters } if sorters
+      Reader.new(graphql, page_id, search_conf: conf)
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/pages.rb

@@ -13,6 +13,7 @@ module Eco::API::UseCases::GraphQL::Helpers
 end
 
 require_relative 'pages/shortcuts'
+require_relative 'pages/activities'
 require_relative 'pages/filters'
 require_relative 'pages/ooze_handlers'
 require_relative 'pages/rescuable'

data/lib/eco/api/usecases/graphql/helpers.rb

@@ -7,3 +7,5 @@ require_relative 'helpers/base'
 require_relative 'helpers/location'
 require_relative 'helpers/contractors'
 require_relative 'helpers/pages'
+require_relative 'helpers/access_logs'
+require_relative 'helpers/dashboards'

data/lib/eco/api/usecases/graphql/samples/contractors/dsl.rb

@@ -1,5 +1,21 @@
 module Eco::API::UseCases::GraphQL::Samples
   module Contractors::DSL
     include Eco::API::UseCases::GraphQL::Helpers::Contractors::Base
+
+    private
+
+    # Sample command: update the org's contractor manager settings (auto-approvals +
+    # whether contractor admins may add other admins). Delegates to the guarded helper
+    # `#update_contractor_manager_settings` (dry-run/simulate + -no-email honoured).
+    #
+    # @param auto_approvals [Hash, nil] AutoApprovalsInput ({ enabled:, approvalConditions: }).
+    # @param allow_admins_add_admins [Boolean, nil]
+    # @return [Hash] the intended input when simulated, else the mutation payload.
+    def update_manager_settings(auto_approvals: nil, allow_admins_add_admins: nil)
+      update_contractor_manager_settings(
+        cm_auto_approvals_settings:            auto_approvals,
+        allow_contractor_admins_to_add_admins: allow_admins_add_admins
+      )
+    end
   end
 end