eco-helpers 3.2.23 → 3.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2803cb1dc211ef8682ebcd33e4007f4e748b5eb42f56ecbaa931b5258064ead8
-  data.tar.gz: 7c0f5f66654761ce6ee5cb37ca4eb354054161c0fc3914c37da27f7f6fce4273
+  metadata.gz: 3c5e64bb2f9a25359774eb01482180a7efdbade0e2b6e4d02a56a4c9dbb1d91f
+  data.tar.gz: ea2fd73dc9709ca1710e9aff527f0ae856a55fe0638a7c3862b71bfd9ce5270c
 SHA512:
-  metadata.gz: 10235574cf1a38826f4de995d715747b65fd657e0ef4e183b04644f8e26bebb2471c4d118fbbc00eac72e174d74c72d4685c9fb49a9a3667d8320c005ef7983a
-  data.tar.gz: e9f15c9f0e9c5243c835402fe64efd1384021773d3e0c0d65fbbfe17bd10128e944932e9a8ac21501cf31025040c9fcc0b2b26b8eb70844fd631f899008c822c
+  metadata.gz: 37dfa8178019e8a4854f3b98386682def2ff8f51b1f7c9dcf95dff4947eea662f14145ab93434ceb8f749acc7981d6904114bc8ad8f4f6d251ed217a28a43ce5
+  data.tar.gz: 4653193b58ac2f88bb76b06c4ee094331b2f034ccae4929d5722398105e2035a982e136fd6fda78d207c33e5ddc4aff9f5c489a11abd155382607d94bca8105d

data/CHANGELOG.md

@@ -2,41 +2,173 @@
 
 All notable changes to this project will be documented in this file.
 
-## [3.2.23] - 2026-09-30
+## [Unreleased]
 
-Security republish of 3.2.22. **Backwards-compatible; no code change**: same dependencies, same
+## [3.3.3] - 2026-09-30
+
+Security republish of 3.3.2. **Backwards-compatible; no code change**: same dependencies, same
 behaviour. Supersedes the published versions of this line, which are to be yanked.
 
 ### Security
 
 - Removed customer and internal identifiers from shipped code comments and this changelog (a
   comment listing customer organisations and their case names; internal repository names and
-  internal documentation paths). Comments and changelog only. It also carries the full-path packaging allowlist from 3.3.2, so the five internal
-  `CLAUDE.md` files that 3.2.22 packaged under `lib/` no longer ship.
+  internal documentation paths). Comments and changelog only.
 - Packaging: the three runtime JSON files are declared in `.release-smoke-allow`, and the release
   tasks accept `release/*` maintenance branches.
 
-## [3.2.22] - 2026-08-14
-
-### Fixed
-
-- Republish of `3.2.21`: its `lib/eco/version.rb` shipped with doubled carriage returns
-  (`
-` line endings), causing a `warning: encountered  in middle of line` on every
-  load. Functionally identical otherwise; `3.2.21` will be yanked.
+## [3.3.2] - 2026-09-02
+
+### Fixed
+
+- Gemspec `spec.files` allowlisted by ROOT DIRECTORY (`lib/`, `exe/`) rather than by full path,
+  so any non-`.rb` file added under `lib/` shipped silently. As of 3.3.1 that was five `CLAUDE.md`
+  agent-instruction files under `lib/eco/api/usecases/`. `spec.files` is now a full-path
+  allowlist — `lib/**/*.rb`, three named JSON files genuinely read at runtime
+  (`preferences_reference.json`, `presets_integrity.json`, `presets_values.json`), and
+  `README.md` / `CHANGELOG.md` / `LICENSE` at the root — intersected with `git ls-files`.
+  `spec/packaging_spec.rb` pins the allowlist so this cannot regress silently again.
 
-## [3.2.21] - 2026-08-14
+## [3.3.1] - 2026-08-13
 
 ### Fixed
 
-- Packaging-only republish of `3.2.19` with an allowlisted gemspec (backported from `3.3.0`).
-  Versions `3.2.16`-`3.2.19` shipped internal repository content (the repo's internal docs tooling,
-  `.claude/settings.json`) to rubygems.org via the old denylist `spec.files`; `3.2.19` is
-  yanked and `3.2.16`/`3.2.18` are queued for deletion by RubyGems support. `3.2.21` is the
-  identical `lib/` code packaged clean, so constraints like `'~> 3.2.0', '>= 3.2.19'` keep
-  resolving on the 3.2 line (its graphql dependency stays `~> 1.3`, satisfied by the clean
-  `1.3.16`). The version number `3.2.20` is intentionally skipped: it exists as a
-  tagged-but-deliberately-unpublished version (see the 3.3.0-era changelog corrections).
+- `Eco::Data::Files::Encoding#get_file_content_with_encoding` read files in **text mode**, which on
+  Windows silently translates `\r\n` to bare `\n` while loading — callers never see the file's
+  actual bytes. Both read branches (BOM and plain) now use binary mode (`mode: 'rb'`), preserving
+  the bytes exactly; BOM stripping is unchanged. Linux behaviour is identical before and after
+  (text mode never translated anything there) — this makes Windows match Linux. Surfaced by Travis
+  on a customer's tooltip CSV (reported from a downstream script repo).
+
+  **Precision note (2026-08-13, verified against the motivating file before this version was
+  tagged):** the earlier draft of this entry claimed `Eco::CSV.read` raised
+  `CSV::MalformedCSVError` on that CSV. It does not — `Eco::CSV.read` parses the collapsed
+  *string*, and a fully collapsed LF-only file with quoted embedded newlines is still legal CSV
+  (502 rows parse fine on 3.3.0). The `MalformedCSVError` in the BLOCKED-TR-04 report came from
+  stdlib `::CSV.read(path)`, whose own IO/row-sep handling is a different code path. The fix here
+  is byte-fidelity hardening: text-mode reads silently *altered data* (any consumer comparing,
+  hashing, or round-tripping file content got different bytes on Windows than on Linux), and
+  partial/mixed line-ending inputs remain genuinely parse-hazardous under translation.
+
+## [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.
+
+★ **CORRECTION (2026-08-13, after publication).** The published 3.3.0 changelog claimed:
+*"Consumers pinned to `~> 3.2` do not pick this up automatically, so adopting graphql 2.0.0 stays a
+deliberate per-repo decision."* **That is wrong** and cannot be edited in the published gem, so it
+is corrected here.
+
+`~> 3.2` means `>= 3.2, < 4.0`, so **3.3.0 is in range** — it is not gated. What actually happens
+depends on whether the consumer also declares graphql directly:
+
+- A consumer declaring **only** `eco-helpers '~> 3.2'` adopts 3.3.0 on its next `bundle update`,
+  and reaches **graphql 2.0.0 transitively**.
+- A consumer declaring **both** `eco-helpers '~> 3.2'` and `ecoportal-api-graphql '~> 1.3'` (which
+  is the case for two internal script repos) does **not** silently adopt — it **fails to
+  resolve**, because 3.3.0 requires graphql `~> 2.0`.
+
+So the "2.0.0 gates adoption for free" argument only ever covered **direct** graphql dependencies.
+Both consumers were pinned deliberately on 2026-08-13 rather than left to discover this.
+
+★ **`3.2.20` was tagged but deliberately NEVER PUBLISHED.** rubygems goes 3.2.19 → 3.3.0. The tag
+marks real history (the point where the 3.2.19 hotfix line rejoined master) but the gem was not
+pushed, and **must not be**: it predates the `spec.files` allowlist fix below and would ship
+internal AI-tooling and `docs/` content to rubygems. Its content is not lost — 3.3.0
+descends from it. Anything needing the `Eco::API::Custom::Cli` reunification must use **3.3.0**,
+not a `~> 3.2.0` pin.
+
+★ **KNOWN AND APPROVED EXCEPTION — `OozeRedirect` ships unverified** (Oscar, 2026-08-13).
+The force path never worked before graphql 1.3.15 and therefore **starts really writing** on this
+release. It was **not** re-verified on a sandbox org before publishing. Approved deliberately:
+the risk is **usage-gated** — `OozeRedirect` lives under `lib/eco/api/usecases/graphql/compat/` and
+is opt-in per use case; nothing invokes it automatically on load or upgrade, so an unused install
+cannot trigger it. Few paths use it, and shipping was judged more important than blocking on the
+check.
+**Revision note:** Travis to verify on a sandbox org **after** release. Until that verification is
+recorded, treat any `OozeRedirect` run against customer data as unproven — dry-run first.
+
+★ **The published gem is now `lib/` only.** `spec.files` excluded just `test|spec|features`, so
+every top-level directory added since shipped by default — internal AI-tooling 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 a downstream CLI 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
 

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

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/command_emitter.rb

@@ -115,8 +115,15 @@ module Eco::API::UseCases::GraphQL::Samples::Pages
         end
 
         # Select-field option. dataFieldId threads the (placeholder) field id.
-        def option(label:, weight: nil)
-          @emitter.emit(:addSelectFieldOption, data_field_id: @field_id, label: label, weight: weight)
+        #
+        # `value:` is a REQUIRED keyword -- the backend's AddSelectFieldOptionInput declares
+        # `argument :value, String, required: true`, and it is the option's unique key (cast to a
+        # number for numeric select fields). There is no default and it is never derived here from
+        # label/weight/position: a plausible-looking derived value would silently store WRONG data on
+        # exactly the scored fields this feature is used for. Callers must supply an explicit value.
+        def option(label:, value:, weight: nil)
+          @emitter.emit(:addSelectFieldOption, data_field_id: @field_id, label: label, value: value,
+                                               weight: weight)
           @field_id
         end
       end

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

@@ -111,7 +111,7 @@ module Eco::API::UseCases::GraphQL::Samples::Pages::Template
           description: field.description
         ) do |field_builder|
           Array(field.options).each do |opt|
-            field_builder.option(label: opt[:label], weight: opt[:weight])
+            field_builder.option(label: opt[:label], value: opt[:value], weight: opt[:weight])
           end
         end
       end

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

@@ -15,8 +15,17 @@ module Eco::API::UseCases::GraphQL::Samples::Pages::Template
     #
     #   * `field_type`     — a template field type accepted by addField (e.g. plain_text, select,
     #                        date, number, gauge, rich_text, people, ...). Passed through verbatim.
-    #   * `field_options`  — for select-type fields: pipe-separated `label:weight` pairs,
-    #                        e.g. "High:10|Medium:5|Low:0". Weight optional ("High|Medium|Low").
+    #   * `field_options`  — for select-type fields: pipe-separated `label:value:weight`
+    #                        triples, e.g. "High:10:10|Medium:5:5|Low:0:0". `value` is the
+    #                        backend's unique, REQUIRED select-option key (cast to a number for
+    #                        numeric select fields) -- NEVER derived from label/weight/position
+    #                        here, because a derived value can collide (duplicates are rejected
+    #                        server-side) or silently store the WRONG number on a scored field.
+    #                        Weight optional via a trailing empty part, e.g. "High:H:|Low:L:". A
+    #                        cell resolving to exactly two parts (the OLD `label:weight`
+    #                        shorthand -- now ambiguous with a value-only `label:value`) or a
+    #                        bare label RAISES ArgumentError naming the field, option label, and
+    #                        offending cell -- see `#options` below.
     #   * `field_description` — carries the SECTION/FIELD IDENTITY convention (see below).
     #
     # SECTION / FIELD IDENTITY CONVENTION (per the CSV-pipeline project notes): stable identity for a
@@ -68,20 +77,50 @@ module Eco::API::UseCases::GraphQL::Samples::Pages::Template
           field_required:    truthy?(row, :field_required),
           field_column:      integer(row, :field_column) || 0,
           field_description: value(row, :field_description),
-          field_options:     options(value(row, :field_options))
+          field_options:     options(value(row, :field_options), field_label: value(row, :field_label))
         )
       end
 
-      # Parse the options cell into [ { label:, weight: }, ... ]. Empty → [].
-      def options(cell)
+      # Parse the options cell into [ { label:, value:, weight: }, ... ]. Empty → [].
+      #
+      # `field_label:` is ONLY used for the ArgumentError message below -- it identifies which field's
+      # options cell is malformed, since a builder raising mid-batch on a 500-row CSV is otherwise
+      # nearly impossible to trace back to the offending row.
+      def options(cell, field_label: nil)
         return [] if cell.nil? || cell.to_s.strip.empty?
 
         cell.to_s.split(OPTIONS_DELIMITER).map do |token|
-          label, weight = token.split(OPTION_WEIGHT_SEPARATOR, 2).map(&:strip)
-          { label: label, weight: (weight && !weight.empty? ? Integer(weight, exception: false) : nil) }
+          option_from_token(token, field_label: field_label, cell: cell)
         end
       end
 
+      # A token must resolve to exactly `label:value` or `label:value:weight` (weight optional, via a
+      # present-but-empty third part). Anything else -- a bare label, or exactly two parts -- means no
+      # explicit `value` was given. Because a `label:X` two-part cell is indistinguishable from the OLD
+      # `label:weight` shorthand, it is REJECTED rather than guessed at: see the module doc for why a
+      # derived value is worse than a loud failure.
+      def option_from_token(token, field_label:, cell:)
+        parts = token.split(OPTION_WEIGHT_SEPARATOR, 3).map(&:strip)
+        label = parts[0].to_s.empty? ? nil : parts[0]
+        value = parts[1]
+
+        if parts.size < 3 || value.nil? || value.empty?
+          raise ArgumentError, missing_option_value_message(field_label, label || token, cell)
+        end
+
+        weight_raw = parts[2]
+        { label: label, value: value,
+          weight: (weight_raw && !weight_raw.empty? ? Integer(weight_raw, exception: false) : nil) }
+      end
+
+      def missing_option_value_message(field_label, option_label, cell)
+        "select option is missing an explicit `value` (field: #{field_label.inspect}, " \
+          "option: #{option_label.inspect}, cell: #{cell.to_s.inspect}). The old `label:weight` " \
+          'two-part shorthand is no longer accepted -- addSelectFieldOption requires a unique, ' \
+          'non-derived `value` per option. Add one explicitly, e.g. ' \
+          "\"#{option_label}:VALUE\" or \"#{option_label}:VALUE:WEIGHT\"."
+      end
+
       def value(row, logical)
         header = COLUMNS.fetch(logical)
         raw    = row[header]

data/lib/eco/data/files/encoding.rb

@@ -26,12 +26,15 @@ module Eco
             puts msg
           end
 
+          # Binary mode: text mode on Windows silently translates "\r\n" to "\n",
+          # which corrupts files whose row terminators must be distinguished from
+          # bare "\n" inside quoted CSV fields (and diverges from Linux behaviour).
           bom_enc = encoding && encoding.split('|')[0] == 'bom'
           if bom?(file) || bom_enc
-            content  = remove_bom(File.read(file, encoding: 'utf-8'))
+            content  = remove_bom(File.read(file, mode: 'rb', encoding: 'utf-8'))
             encoding = 'utf-8'
           else
-            content = File.read(file, encoding: encoding)
+            content = File.read(file, mode: 'rb', encoding: encoding)
           end
 
           return unless content

data/lib/eco/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 3.2.23
+  version: 3.3.3
 platform: ruby
 authors:
 - Oscar Segura
@@ -242,7 +242,7 @@ dependencies:
         version: '0.10'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.10.14
+        version: 0.10.17
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -252,27 +252,27 @@ dependencies:
         version: '0.10'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.10.14
+        version: 0.10.17
 - !ruby/object:Gem::Dependency
   name: ecoportal-api-graphql
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.14
+        version: 2.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.14
+        version: 2.0.0
 - !ruby/object:Gem::Dependency
   name: ecoportal-api-v2
   requirement: !ruby/object:Gem::Requirement
@@ -619,6 +619,7 @@ files:
 - lib/eco/api/common/version_patches/ruby3.rb
 - lib/eco/api/common/version_patches/ruby3/object.rb
 - lib/eco/api/custom.rb
+- lib/eco/api/custom/cli.rb
 - lib/eco/api/custom/config.rb
 - lib/eco/api/custom/error_handler.rb
 - lib/eco/api/custom/mailer.rb
@@ -826,13 +827,21 @@ files:
 - lib/eco/api/usecases/graphql/compat/parity/harness.rb
 - lib/eco/api/usecases/graphql/compat/parity/run_result.rb
 - lib/eco/api/usecases/graphql/helpers.rb
+- lib/eco/api/usecases/graphql/helpers/access_logs.rb
+- lib/eco/api/usecases/graphql/helpers/access_logs/base.rb
+- lib/eco/api/usecases/graphql/helpers/access_logs/base/reader.rb
 - lib/eco/api/usecases/graphql/helpers/base.rb
 - lib/eco/api/usecases/graphql/helpers/base/case_env.rb
+- lib/eco/api/usecases/graphql/helpers/base/connection_reader.rb
 - lib/eco/api/usecases/graphql/helpers/base/error_handling.rb
 - lib/eco/api/usecases/graphql/helpers/base/graphql_env.rb
 - lib/eco/api/usecases/graphql/helpers/contractors.rb
 - lib/eco/api/usecases/graphql/helpers/contractors/base.rb
 - lib/eco/api/usecases/graphql/helpers/contractors/base/load.rb
+- lib/eco/api/usecases/graphql/helpers/contractors/base/manager_settings.rb
+- lib/eco/api/usecases/graphql/helpers/dashboards.rb
+- lib/eco/api/usecases/graphql/helpers/dashboards/base.rb
+- lib/eco/api/usecases/graphql/helpers/dashboards/base/reader.rb
 - lib/eco/api/usecases/graphql/helpers/location.rb
 - lib/eco/api/usecases/graphql/helpers/location/base.rb
 - lib/eco/api/usecases/graphql/helpers/location/base/classifications_parser.rb
@@ -858,6 +867,7 @@ files:
 - lib/eco/api/usecases/graphql/helpers/location/tags_remap/tags_map.rb
 - lib/eco/api/usecases/graphql/helpers/location/tags_remap/tags_set.rb
 - lib/eco/api/usecases/graphql/helpers/pages.rb
+- lib/eco/api/usecases/graphql/helpers/pages/activities.rb
 - lib/eco/api/usecases/graphql/helpers/pages/copying.rb
 - lib/eco/api/usecases/graphql/helpers/pages/creatable.rb
 - lib/eco/api/usecases/graphql/helpers/pages/filters.rb