eco-helpers 3.2.23 → 3.3.0

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

@@ -7,12 +7,13 @@ module Eco::API::UseCases::GraphQL::Helpers
   # with duck-typing so they work against the GraphQL page/section/field models.
   #
   # This is Phase 1 of the ooze -> native GraphQL migration (build the shared substrate before
-  # any case). See the ecoportal-api-graphql repo's internal docs.
+  # any case). See ecoportal-api-graphql/.ai-assistance/projects/ooze-graphql-native-migration/.
   module Pages
   end
 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/CLAUDE.md

@@ -0,0 +1,76 @@
+# usecases/graphql/samples
+
+Built-in GraphQL sample base classes shipped with the gem.
+These are abstract/semi-abstract classes that org scripts inherit from.
+Concrete, CLI-integrated cases go in `usecases/default/` instead.
+
+---
+
+## Hierarchy convention
+
+Each domain follows:
+```
+samples/<domain>.rb              ← namespace loader (may also BE the base class)
+samples/<domain>/
+  <level>/
+    dsl.rb                       ← DSL concern — include in base, available to subclasses
+    base.rb                      ← Base class (inherits from GraphQL::Base or parent level)
+    <functional_level>.rb        ← Optional: opinionated subclass, inherit directly
+    <functional_level>/
+      dsl.rb                     ← Further DSL for that functional level
+```
+
+DSLs are always **concerns (modules)** to include — never classes.
+Bases are **classes** with the scaffolding logic.
+Functional levels add opinionated defaults on top of base.
+
+---
+
+## Contents
+
+| File | Class | Purpose |
+|------|-------|---------|
+| `samples/location.rb` | `Samples::Location` | Location structure management |
+| `samples/location/command.rb` | `Samples::Location::Command` | Apply location tree commands |
+| `samples/location/service.rb` | `Samples::Location::Service` | Tree diffing and conversion service |
+| `samples/contractors.rb` | `Samples::Contractors` | Contractor entity base case |
+| `samples/contractors/dsl.rb` | `Contractors::DSL` | Contractor helper mixin |
+| `samples/pages.rb` | `Samples::Pages` (namespace) | Page processing cases loader |
+| `samples/pages/page/dsl.rb` | `Pages::Page::DSL` | SearchConf helpers mixin |
+| `samples/pages/page/base.rb` | `Pages::Page::Base` | Register-scoped page iteration |
+| `samples/pages/org_page/dsl.rb` | `Pages::OrgPage::DSL` | Org-page DSL (extends Page::DSL) |
+| `samples/pages/org_page/base.rb` | `Pages::OrgPage::Base` | Org-wide page iteration |
+
+---
+
+## Difference: samples vs org-specific cases vs default
+
+| Layer | Location | Purpose |
+|---|---|---|
+| **samples** (here) | `eco-helpers/lib/.../graphql/samples/` | Abstract base classes — org scripts inherit |
+| **default** | `eco-helpers/lib/.../usecases/default/` | Concrete CLI-integrated cases for ALL orgs |
+| **org-specific** | `multi_org_api/{org}/config/graphql_cases/` | Org-specific implementations |
+
+Org scripts inherit from `samples/`, optionally via `default/` as an intermediate layer.
+
+---
+
+## Adding a new built-in sample
+
+1. Create the case file in `samples/`:
+   ```ruby
+   # lib/eco/api/usecases/graphql/samples/my_domain.rb
+   class Eco::API::UseCases::GraphQL::Samples::MyDomain < Eco::API::UseCases::GraphQL::Base
+     name 'my-domain-case'
+     type :other
+
+     def process
+       # ...
+     end
+   end
+   ```
+
+2. Add `require_relative 'samples/my_domain'` to `samples.rb`.
+
+If the case is page-centric, inherit from `PageCase` instead of `Base` to get
+pagination, KPI tracking, and `update_page` for free.

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

data/lib/eco/api/usecases/graphql/samples/pages/CLAUDE.md

@@ -0,0 +1,59 @@
+# samples/pages
+
+Base classes for GraphQL-native page processing use cases.
+
+---
+
+## Structure
+
+```
+pages/
+  page/
+    dsl.rb          ← Page::DSL — SearchConf helpers mixin (sc, in_register, state_is, ...)
+    base.rb         ← Page::Base — register-scoped page iteration + KPI scaffolding
+  org_page/
+    dsl.rb          ← OrgPage::DSL — extends Page::DSL (org-wide helpers)
+    base.rb         ← OrgPage::Base — org-wide iteration (no default register scope)
+```
+
+---
+
+## Inheritance
+
+```
+GraphQL::Base
+    ↓
+Samples::Pages::Page::Base          (register-scoped, inherits Page::DSL)
+    ↓
+Samples::Pages::OrgPage::Base       (org-wide, overrides search_conf)
+    ↓
+your org subclass
+```
+
+---
+
+## Page::Base — register-scoped scripts
+
+Override `process_page(page)` and optionally `search_conf`.
+Set `register_id` and `batch_size` on the class.
+
+## OrgPage::Base — org-wide scripts
+
+Same as Page::Base but `search_conf` starts empty.
+Add your own filters via `super.filter(state_is(:active))` etc.
+
+---
+
+## Adding a functional level
+
+If a common pattern emerges (e.g., "stage-submit scripts"), add:
+
+```
+pages/page/
+  stage_submitter.rb          ← Page::StageSubmitter < Page::Base
+  stage_submitter/
+    dsl.rb                    ← StageSubmitter::DSL
+```
+
+Keep base.rb for the pure iteration scaffolding; put opinionated defaults in
+the functional level so scripts can choose their entry point.

data/lib/eco/api/usecases/graphql/samples/pages/template/base.rb

@@ -1,4 +1,11 @@
 module Eco::API::UseCases::GraphQL::Samples::Pages
+  # NOTE: nested as `module Template` + `class Base` rather than the compact `class Template::Base`
+  # ON PURPOSE. The compact form leaves `Template` out of this file's lexical scope, so the bare
+  # `CommandEmitter` reference in #desired_commands resolved against Base and Pages only and raised
+  # NameError on every call -- the class could never run. Sibling files (command_emitter.rb,
+  # csv_build/builder.rb) all open the Template module properly, which is why their bare references
+  # to each other work. Keep this nesting.
+  #
   # Build-from-scratch template (workflow) construction use case.
   #
   # A subclass declares the desired template structure in #declare(emitter) using the
@@ -17,54 +24,56 @@ module Eco::API::UseCases::GraphQL::Samples::Pages
   #       end
   #     end
   #   end
-  class Template::Base < Eco::API::UseCases::GraphQL::Base
-    name 'graphql-template-base'
-    type :other
+  module Template
+    class Base < Eco::API::UseCases::GraphQL::Base
+      name 'graphql-template-base'
+      type :other
 
-    require_relative 'command_emitter'
+      require_relative 'command_emitter'
 
-    def process
-      commands = desired_commands
-      if simulate?
-        log(:info) { preview_message(commands) }
-        return nil
+      def process
+        commands = desired_commands
+        if simulate?
+          log(:info) { preview_message(commands) }
+          return nil
+        end
+        apply(commands)
       end
-      apply(commands)
-    end
 
-    # == Subclass override point ================================================
+      # == Subclass override point ================================================
 
-    # Declare the desired template structure onto the given CommandEmitter.
-    def declare(_emitter)
-      raise NotImplementedError, "Implement #declare(emitter) in #{self.class}"
-    end
+      # Declare the desired template structure onto the given CommandEmitter.
+      def declare(_emitter)
+        raise NotImplementedError, "Implement #declare(emitter) in #{self.class}"
+      end
 
-    # The ordered command batch this template would apply. Pure — no client needed.
-    def desired_commands
-      emitter = CommandEmitter.new
-      declare(emitter)
-      emitter.commands
-    end
+      # The ordered command batch this template would apply. Pure — no client needed.
+      def desired_commands
+        emitter = CommandEmitter.new
+        declare(emitter)
+        emitter.commands
+      end
 
-    protected
+      protected
 
-    # Persist a fresh template from the command batch. Override to #update an existing one.
-    def apply(commands)
-      graphql.template.create(commands: commands)
-    end
+      # Persist a fresh template from the command batch. Override to #update an existing one.
+      def apply(commands)
+        graphql.template.create(commands: commands)
+      end
 
-    # Update an existing template model with the command batch.
-    def apply_update(model, commands)
-      graphql.template.update(model, commands: commands)
-    end
+      # Update an existing template model with the command batch.
+      def apply_update(model, commands)
+        graphql.template.update(model, commands: commands)
+      end
 
-    private
+      private
 
-    def preview_message(commands)
-      [
-        "Simulate — would apply #{commands.size} workflow command(s):",
-        *commands.map { |c| "  * #{c.keys.first}: #{c.values.first.inspect}" }
-      ].join("\n")
+      def preview_message(commands)
+        [
+          "Simulate — would apply #{commands.size} workflow command(s):",
+          *commands.map { |c| "  * #{c.keys.first}: #{c.values.first.inspect}" }
+        ].join("\n")
+      end
     end
   end
 end

data/lib/eco/api/usecases/graphql/samples/pages/template.rb

@@ -1,6 +1,6 @@
 module Eco::API::UseCases::GraphQL::Samples::Pages
   # Template (workflow) build-from-scratch + (later) diff-and-update samples.
-  # See the ecoportal-api-graphql repo's internal docs.
+  # See ecoportal-api-graphql/.ai-assistance/projects/template-maintenance/.
   module Template
   end
 end

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = '3.2.23'.freeze
+  VERSION = '3.3.0'.freeze
 end