eco-helpers 3.2.14 → 3.2.22

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/location/command/service/tree_update.rb

@@ -57,7 +57,7 @@ class Eco::API::UseCases::GraphQL::Samples::Location
           digest_msgs  << "\n#{exception.patch_full_message(trace_count: 3)}" if exception
 
           session.mail(subject: subject, body: digest_msgs.join).tap do
-            options.deep_merge!({worfklow: {no_email: true}})
+            options.deep_merge!({workflow: {no_email: true}})
           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/org_page/base.rb

@@ -0,0 +1,41 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Base class for **org-wide** page processing use cases.
+  #
+  # Identical to Page::Base but with no default register scope — search_conf
+  # starts empty (all org pages). Subclass adds filters via super.
+  #
+  # == When to use which
+  #
+  #   Page::Base    — one register, most scripts ("go through all pages in Reg X")
+  #   OrgPage::Base — entire org (cross-register audits, archive sweeps, bulk ops)
+  #
+  # == Subclass interface
+  #
+  #   class Custom::UseCase::ArchiveStaleDrafts < Eco::API::UseCases::GraphQL::Samples::Pages::OrgPage::Base
+  #     name 'archive-stale-drafts'
+  #     batch_size 100
+  #
+  #     def search_conf
+  #       super.filter(state_is(:draft))
+  #            .filter(updated_since('2025-01-01'))
+  #     end
+  #
+  #     def process_page(page)
+  #       return skip('already archived') if page.archived?
+  #       log(:info) { "Archiving: #{page.name}" }
+  #       graphql.page.archive(input: { id: page.id }) unless simulate?
+  #     end
+  #   end
+  class OrgPage::Base < Page::Base
+    name 'graphql-org-page-base'
+    type :other
+
+    require_relative 'dsl'
+    include Eco::API::UseCases::GraphQL::Samples::Pages::OrgPage::DSL
+
+    # No default register scope. Subclass adds filters via super.
+    def search_conf
+      sc.new
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/org_page/dsl.rb

@@ -0,0 +1,8 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::OrgPage
+  # DSL concern for org-wide page use cases.
+  # Includes Page::DSL — all SearchConf helpers are available.
+  # Add org-page-specific helpers here as the pattern grows.
+  module DSL
+    include Eco::API::UseCases::GraphQL::Samples::Pages::Page::DSL
+  end
+end

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

@@ -0,0 +1,7 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  module OrgPage
+  end
+end
+
+require_relative 'org_page/dsl'
+require_relative 'org_page/base'

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

@@ -0,0 +1,148 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Base class for **register-scoped** page processing use cases.
+  #
+  # Provides the iteration + KPI scaffolding mirroring RegisterUpdateCase
+  # from OozeSamples, but working natively with the GraphQL stack.
+  #
+  # == Subclass interface
+  #
+  #   class Custom::UseCase::UpdateRiskRating < Eco::API::UseCases::GraphQL::Samples::Pages::Page::Base
+  #     name 'update-risk-rating'
+  #     register_id 'REG_ABC123'
+  #     batch_size 50
+  #
+  #     # Add filters on top of the default register scope.
+  #     def search_conf
+  #       super.filter(state_is(:active))
+  #            .filter(updated_since(options.dig(:filters, :from).to_s))
+  #     end
+  #
+  #     # Transform or act on each page; call update_page(page) to persist.
+  #     def process_page(page)
+  #       field = page.components.get_by_name('Risk Level')
+  #       return skip('no risk field') unless field
+  #       page.name = "[HIGH] #{page.name}" if field.value == 'High'
+  #       update_page(page)
+  #     end
+  #   end
+  #
+  # == What the base provides
+  # * process_page(page) — override point (required)
+  # * search_conf        — override point (optional; default scopes to register_id)
+  # * update_page(page)  — from_model + simulate? guard + error tracking
+  # * skip(reason)       — record a non-error skip
+  # * each_page          — cursor-paginated org search
+  # * KPI tracking       — total / processed / updated / skipped / failed
+  class Page::Base < Eco::API::UseCases::GraphQL::Base
+    name 'graphql-page-base'
+    type :other
+
+    require_relative 'dsl'
+    include Eco::API::UseCases::GraphQL::Samples::Pages::Page::DSL
+
+    class << self
+      def batch_size(size = nil)
+        @batch_size ||= 50
+        return @batch_size unless size
+        @batch_size = size
+      end
+
+      def register_id(id = nil)
+        @register_id = id if id
+        @register_id
+      end
+    end
+
+    attr_reader :total_pages, :processed_pages, :updated_pages
+    attr_reader :failed_pages, :skipped_pages
+
+    # Entry point — called by GraphQL::Base#main.
+    def process
+      init_kpis
+      each_page do |page|
+        process_page(page)
+        @processed_pages += 1
+      end
+      log_kpis
+    end
+
+    # == Subclass override points ==============================================
+
+    # Transform or act on one page. Call update_page(page) to persist changes.
+    def process_page(_page)
+      raise NotImplementedError, "Implement #process_page in #{self.class}"
+    end
+
+    # Return a SearchConf for the page search. Override to add filters.
+    # Default: scoped to register_id when set, otherwise all pages.
+    def search_conf
+      conf = sc.new
+      reg  = self.class.register_id
+      conf = conf.filter(in_register(reg)) if reg
+      conf
+    end
+
+    protected
+
+    # Record a skip (not an error — the page was intentionally not processed).
+    def skip(reason = nil)
+      @skipped_pages += 1
+      log(:debug) { "Skipped#{reason ? ": #{reason}" : ''}" }
+    end
+
+    # Persist a page. Wraps Input::Page::Update.from_model, respects simulate?,
+    # and tracks KPIs. Returns nil on simulate or no-change; Response otherwise.
+    def update_page(page, **kargs)
+      if simulate?
+        @skipped_pages += 1
+        log(:debug) { "Simulate — would update page #{page.id}" }
+        return nil
+      end
+      response = graphql.pages.update(page, **kargs)
+      if response.nil?
+        @skipped_pages += 1
+      elsif response.success?
+        @updated_pages += 1
+      else
+        @failed_pages += 1
+        log(:error) { "Failed to update page #{page.id}: #{response.body}" }
+      end
+      response
+    end
+
+    # Cursor-paginated iteration over pages matching search_conf.
+    # Uses org search (currentOrganization.pages) — returns full PageUnion
+    # with patchVer and field IDs (required for update workflows).
+    def each_page(conf: search_conf, first: self.class.batch_size, &block)
+      graphql.pages.each(search_conf: conf.to_h, first: first) do |page|
+        @total_pages += 1
+        yield page
+      end
+    end
+
+    private
+
+    def init_kpis
+      @total_pages     = 0
+      @processed_pages = 0
+      @updated_pages   = 0
+      @failed_pages    = 0
+      @skipped_pages   = 0
+    end
+
+    def log_kpis
+      log(:info) { kpis_message }
+    end
+
+    def kpis_message
+      [
+        'Run end:',
+        "  * Pages found:     #{total_pages}",
+        "  * Pages processed: #{processed_pages}",
+        "  * Updated:         #{updated_pages}",
+        "  * Skipped:         #{skipped_pages}",
+        "  * Failed:          #{failed_pages}"
+      ].join("\n")
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/page/dsl.rb

@@ -0,0 +1,38 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Page
+  # DSL concern — included in Page::Base and available to all Page subclasses.
+  # Provides the SearchConf accessor and common filter shorthand methods.
+  #
+  # Include this in any class that needs SearchConf DSL access without
+  # inheriting the full Page::Base iteration scaffolding.
+  module DSL
+    private
+
+    # Lazy accessor for the SearchConf builder class.
+    # Resolved at runtime so the ecoportal-api-graphql gem is guaranteed to be loaded.
+    # Subclasses can also define a local constant for brevity:
+    #   SearchConf = Ecoportal::API::GraphQL::Input::SearchConf
+    def sc
+      Ecoportal::API::GraphQL::Input::SearchConf
+    end
+
+    # Convenience: build a register-scoped filter object.
+    def in_register(*ids)
+      sc.in_register(*ids)
+    end
+
+    # Convenience: build a state equality filter.
+    def state_is(value)
+      sc[:state].is(value)
+    end
+
+    # Convenience: build an externalId equality filter.
+    def external_id_eq(value)
+      sc[:external_id].eq(value)
+    end
+
+    # Convenience: build an updated_at since filter.
+    def updated_since(iso8601, time_zone: 'UTC')
+      sc[:updated_at].since(iso8601, time_zone: time_zone)
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  module Page
+  end
+end
+
+require_relative 'page/dsl'
+require_relative 'page/base'

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

@@ -0,0 +1,181 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Native GraphQL re-expression of OozeSamples::RegisterUpdateCase.
+  #
+  # Register-scoped page processing: iterate the entries of a register in
+  # cursor-paginated batches, hand each page to `process_page` (a.k.a.
+  # `process_ooze` for naming parity with the v2 case), and track KPI counters
+  # over the whole run. Supports creating new entries via the native Creatable.
+  #
+  # This reproduces the SHAPE of RegisterUpdateCase (batched search, dedup-by-id,
+  # search/retrieved/updated/created/failed counters, a dry-run preview) natively,
+  # without the Ecoportal::API::V2 queue/enqueue coupling: the GraphQL update path
+  # is per-page (graphql.pages.update) rather than a batched patch queue, so the
+  # v2 batch_queue / enqueue / queue_shift machinery is intentionally dropped.
+  #
+  # == Subclass interface
+  #
+  #   class Custom::UseCase::CloseOldEntries < Eco::API::UseCases::GraphQL::Samples::Pages::Register::Base
+  #     name 'close-old-entries'
+  #     register_id 'REG_ABC123'
+  #     batch_size 25
+  #
+  #     def process_page(page)
+  #       return skip('not stale') unless stale?(page)
+  #       page.name = "[CLOSED] #{page.name}"
+  #       update_page(page)
+  #     end
+  #   end
+  #
+  # `register_id` may also come from `options[:source][:register_id]` (v2 parity),
+  # which takes precedence over the class-level declaration when present.
+  class Register::Base < Page::Base
+    include Eco::API::UseCases::GraphQL::Helpers::Pages::Shortcuts
+    include Eco::API::UseCases::GraphQL::Helpers::Pages::OozeHandlers
+    include Eco::API::UseCases::GraphQL::Helpers::Pages::Rescuable
+    include Eco::API::UseCases::GraphQL::Helpers::Pages::Creatable
+
+    name 'graphql-register-base'
+    type :other
+
+    class << self
+      def batch_size(size = nil)
+        @batch_size ||= 25
+        return @batch_size unless size
+
+        @batch_size = size
+      end
+    end
+
+    attr_reader :total_search_pages, :dupped_search_pages
+    attr_reader :retrieved_pages, :page_result_ids
+    attr_reader :created_pages, :page_create_attempts
+
+    # Entry point — called by GraphQL::Base#main.
+    def process
+      init_kpis
+      results_preview
+      each_page do |page|
+        process_page(page)
+        @processed_pages += 1
+      end
+      log_kpis
+    end
+
+    # == Subclass override points ==============================================
+
+    # Transform or act on one page. Call update_page(page) to persist changes.
+    # Alias `process_ooze` is provided for naming parity with the v2 case.
+    def process_page(_page)
+      raise NotImplementedError, "Implement #process_page in #{self.class}"
+    end
+
+    # Naming-parity alias for the v2 case. Forwards (rather than alias_method) so a
+    # subclass overriding #process_page is honoured when called as #process_ooze.
+    def process_ooze(page)
+      process_page(page)
+    end
+
+    # Return the register id to scope the search to.
+    # `options[:source][:register_id]` (v2 parity) wins over the class declaration.
+    def register_id
+      options.dig(:source, :register_id) || self.class.register_id
+    end
+
+    # Return a SearchConf for the page search. Override to add filters.
+    # Default: scoped to register_id (raises if none configured — a register case
+    # without a register would silently scan the whole org).
+    def search_conf
+      reg = register_id
+      raise ArgumentError, 'No register_id configured (class register_id or options[:source][:register_id])' unless reg
+
+      sc.new.filter(in_register(reg))
+    end
+
+    protected
+
+    # Typed value merge for a GraphQL data field. Convenience over OozeHandlers#merge_values
+    # that reads the field's own #type so a subclass need not pass it explicitly.
+    #
+    #   fld = page.components.get_by_name('Notes')
+    #   fld.value = merge_field_values(fld, incoming_notes)
+    #
+    # @param field [#type] a GraphQL DataField (or anything responding to #type).
+    # @param append [Object] the value to merge onto the field's current value.
+    # @param origin [Object] the base value; defaults to the field's current #value.
+    # @param delimiter [String] delimiter for :delimiter-strategy types.
+    # @return [Object] the merged value.
+    def merge_field_values(field, append, origin: nil, delimiter: "\n")
+      base = origin.nil? && field.respond_to?(:value) ? field.value : origin
+      merge_values(base, append, type: field, delimiter: delimiter)
+    end
+
+    # Launches the actual creation of the entry (hook driven by Creatable).
+    # Respects simulate? for dry-run; on live create, bumps the created counter.
+    # @return [Ecoportal::API::GraphQL::Compat::PageReference, false]
+    def create_ooze(draft, template_id: draft&.template_id)
+      @page_create_attempts += 1
+      if simulate?
+        dry_run_feedback(draft)
+        return false
+      end
+
+      graphql.pages.create(draft, from: template_id).tap do |result|
+        @created_pages += 1 if result.respond_to?(:page_id) && result.page_id
+      end
+    end
+
+    # Cursor-paginated iteration over the register's pages. Counts total search
+    # results and flags duplicated page ids (dedup-by-id, v2 parity).
+    def each_page(conf: search_conf, first: self.class.batch_size)
+      graphql.pages.each(search_conf: conf.to_h, first: first) do |page|
+        @total_search_pages += 1
+        if page_result_ids[page.id]
+          @dupped_search_pages += 1
+        else
+          page_result_ids[page.id] = true
+          @total_pages += 1
+        end
+        @retrieved_pages += 1
+        yield page
+      end
+    end
+
+    private
+
+    # Dry-run preview of what a create WOULD send. Faithful but scoped: the
+    # GraphQL cursor search offers no cheap "total before filtering" count like the
+    # v2 registers.search(only_first:), so there is no up-front count prompt here.
+    def dry_run_feedback(draft)
+      log(:info) { "Simulate — would create page from template #{draft&.template_id}" }
+      nil
+    end
+
+    def results_preview
+      log(:info) { "Processing register '#{register_id}' in batches of #{self.class.batch_size}" }
+    end
+
+    def init_kpis
+      super
+      @total_search_pages   = 0
+      @dupped_search_pages  = 0
+      @retrieved_pages      = 0
+      @page_result_ids      = {}
+      @created_pages        = 0
+      @page_create_attempts = 0
+    end
+
+    def kpis_message
+      [
+        'Run end:',
+        "  * Search results:  #{total_search_pages}",
+        "  * Duplicated:      #{dupped_search_pages}",
+        "  * Retrieved:       #{retrieved_pages}",
+        "  * Processed:       #{processed_pages}",
+        "  * Updated:         #{updated_pages} (of #{total_pages} unique)",
+        "  * Created:         #{created_pages} (of #{page_create_attempts} attempts)",
+        "  * Skipped:         #{skipped_pages}",
+        "  * Failed:          #{failed_pages}"
+      ].join("\n")
+    end
+  end
+end