eco-helpers 3.2.13 → 3.2.16

data/lib/eco/api/usecases/default/utils/group_csv_case/file_handler.rb

@@ -0,0 +1,62 @@
+class Eco::API::UseCases::Default::Utils::GroupCsv
+  class FileHandler
+    attr_reader :filename, :format
+
+    def initialize(filename, format: :csv)
+      @filename = filename
+      @format   = format
+
+      open
+    end
+
+    def <<(value)
+      msg = "File has been closed. Can't write to it: #{filename}"
+      raise msg unless file
+
+      case format
+      when :csv
+        file << value
+      when :jsonl
+        file.puts to_s(value)
+      end
+    end
+
+    def close
+      return if file.nil?
+
+      file.close.tap do
+        @file = nil
+      end
+    end
+
+    private
+
+    attr_reader :file
+
+    def to_s(value)
+      case value
+      when String
+        value.split("\n").first.tap do |line|
+          next if line == value
+
+          raise ArgumentError, "As string, value should be a single line. Given: #{value}"
+        end
+      when Hash
+        value.to_json
+      else
+        raise ArgumentError, "Unsupported type: #{value.class}"
+      end
+    end
+
+    def open
+      case format
+      when :csv
+        @file = CSV.open(filename, 'wb')
+      when :jsonl
+        @file = File.open(filename, 'wb')
+      else
+        raise "Unknown output format: #{format}"
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/default/utils/group_csv_case.rb

@@ -1,35 +1,59 @@
 # This script assumes that for the `GROUP_BY_FIELD` rows are consecutive.
 # @note you might run first the `sort-csv` case.
+# @note when using `jsonl` as an output `format`, it doesn't merge fields,
+#   but it groups them based on some criteria.
+#   - In this case you need to define a `json_builder` method that returns a hash.
 # @note you must inherit from this case and define the constants.
 #
-#      GROUP_BY_FIELD = 'target_csv_field'.freeze
+#      GROUP_BY_FIELD = 'target_csv_field'.freeze # if `-by` command option isn't used
 #      GROUPED_FIELDS = [
 #        'joined_field_1',
 #        'joined_field_2',
 #        'joined_field_3',
 #      ].freeze
-#
+# @note that `GROUPED_FIELDS` isn't necessary if `jsonl` is used as an output `format`
 class Eco::API::UseCases::Default::Utils::GroupCsv < Eco::API::Custom::UseCase
   name 'group-csv'
   type :other
 
   require_relative 'cli/group_csv_cli'
+  require_relative 'group_csv_case/file_handler'
+
+  OUTPUT_FORMAT = :csv # :csv or :jsonl
 
   def main(*_args)
     if simulate?
       count = Eco::CSV.count(input_file)
       log(:info) { "CSV '#{input_file}' has #{count} rows." }
     else
+      msg = "You should define a json_builder method when using jsonl as output format"
+      raise msg unless respond_to?(:json_builder, true) || output_format != :jsonl
+
       generate_file
     end
   end
 
   private
 
+  attr_reader :in_index
+
+  def with_output_file
+    handler = FileHandler.new(output_filename, format: output_format)
+
+    yield handler
+  ensure
+    handler&.close
+
+    msg  = "Generated file '#{output_filename}' "
+    msg << "with #{row_count} rows (out of #{in_index + 1})."
+
+    log(:info) { msg } unless simulate?
+  end
+
   def generate_file # rubocop:disable Metrics/AbcSize
-    in_index = nil
+    @in_index = nil
 
-    CSV.open(output_filename, 'wb') do |out_csv|
+    with_output_file do |f_handler|
       first = true
 
       puts "\n"
@@ -38,11 +62,11 @@ class Eco::API::UseCases::Default::Utils::GroupCsv < Eco::API::Custom::UseCase
         if first
           first = false
           headers!(row)
-          out_csv << headers
+          f_handler << headers if output_format == :csv
           require_group_by_field!(row, file: input_file)
         end
 
-        in_index = idx
+        @in_index = idx
         next unless !block_given? || yield(row, idx)
 
         next unless pivotable?(row, idx)
@@ -50,19 +74,25 @@ class Eco::API::UseCases::Default::Utils::GroupCsv < Eco::API::Custom::UseCase
 
         row_count!
 
-        out_csv << last_group.values_at(*headers)
+        case output_format
+        when :csv
+          f_handler << last_group.values_at(*headers)
+        when :jsonl
+          f_handler << json_builder(last_group)
+        end
       end
 
       # finalize
       if (l_row = pivot_row)
         row_count!
-        out_csv   << l_row.values_at(*headers)
-      end
-    ensure
-      msg  = "Generated file '#{output_filename}' "
-      msg << "with #{row_count} rows (out of #{in_index + 1})."
 
-      log(:info) { msg } unless simulate?
+        case output_format
+        when :csv
+          f_handler << l_row.values_at(*headers)
+        when :jsonl
+          f_handler << json_builder(l_row)
+        end
+      end
     end
   end
 
@@ -76,16 +106,23 @@ class Eco::API::UseCases::Default::Utils::GroupCsv < Eco::API::Custom::UseCase
     pivot_value = row[group_by_field]
 
     unless (last_pivot = @group[group_by_field])
+      # init
       last_pivot = @group[group_by_field] = pivot_value
     end
 
     last   = @group
     @group = {group_by_field => pivot_value} unless pivot_value == last_pivot
 
-    headers_rest.each do |field|
-      curr_values   = row[field].to_s.split('|').compact.uniq
-      pivot_values  = @group[field].to_s.split('|').compact.uniq
-      @group[field] = (pivot_values | curr_values).join('|')
+    case output_format
+    when :csv
+      headers_rest.each do |field|
+        curr_values   = row[field].to_s.split('|').compact.uniq
+        group_values  = @group[field].to_s.split('|').compact.uniq
+        @group[field] = (group_values | curr_values).join('|')
+      end
+    when :jsonl
+      @group['rows'] ||= []
+      @group['rows'] << row.to_h.slice(*headers_rest)
     end
 
     last unless last == @group
@@ -97,9 +134,10 @@ class Eco::API::UseCases::Default::Utils::GroupCsv < Eco::API::Custom::UseCase
   def headers!(row)
     return if headers?
 
-    @headers_rest  = grouped_fields & row.headers
-    @headers_rest -= [group_by_field]
-    @headers       = [group_by_field, *headers_rest]
+    @grouped_fields = row.headers - [group_by_field] if output_format == :jsonl
+    @headers_rest   = grouped_fields & row.headers
+    @headers_rest  -= [group_by_field]
+    @headers        = [group_by_field, *headers_rest]
   end
 
   def headers?
@@ -108,7 +146,7 @@ class Eco::API::UseCases::Default::Utils::GroupCsv < Eco::API::Custom::UseCase
 
   def row_count!
     @row_count ||= 0
-    (@row_count  += 1).tap do |cnt|
+    (@row_count += 1).tap do |cnt|
       if (cnt % 500).zero?
         print "... Done #{cnt} rows            \r"
         $stdout.flush
@@ -141,10 +179,14 @@ class Eco::API::UseCases::Default::Utils::GroupCsv < Eco::API::Custom::UseCase
     num
   end
 
+  def output_format
+    options.dig(:output, :format)&.to_sym || self.class::OUTPUT_FORMAT
+  end
+
   def output_filename
     return unless input_name
 
-    File.join(input_dir, "#{input_name}_grouped#{input_ext}")
+    File.join(input_dir, "#{input_name}_grouped.#{output_format}")
   end
 
   def input_name

data/lib/eco/api/usecases/default/utils/track_files_case.rb

@@ -0,0 +1,179 @@
+# Tracks the files of a source folder into a file
+class Eco::API::UseCases::Default::Utils::TrackFiles < Eco::API::Custom::UseCase
+  name 'track-files'
+  type :other
+
+  require_relative 'cli/track_files_cli'
+
+  OUT_HEADERS = %w[
+    ref_id
+    filename
+    filesize
+    s3_path
+  ].freeze
+
+  REF_ID_PATH_POSITION = :last
+  BASE_S3_PATH         = 'uploads'.freeze
+  # S3_SUBPATH   = 'org-name'.freeze
+
+  def main(*_args)
+    if simulate?
+      count_files
+    else
+      generate_file
+    end
+  end
+
+  private
+
+  attr_reader :folder_count, :file_count
+
+  def folder_count!(cnt = 1)
+    @folder_count ||= 0
+
+    print '.'
+    @folder_count += cnt
+  end
+
+  def file_count!(cnt = 1)
+    @file_count ||= 0
+    @file_count  += cnt
+  end
+
+  def count_files
+    with_each_file
+
+    log(:info) {
+      "Found #{file_count} files, in #{folder_count} folders (with files)."
+    }
+  end
+
+  def ref_id_path_position
+    self.class::REF_ID_PATH_POSITION
+  end
+
+  def generate_file
+    CSV.open(output_filename, 'wb') do |csv|
+      csv << self.class::OUT_HEADERS
+
+      with_each_file do |file, src_path|
+        ref_id =
+          case ref_id_path_position
+          when :first then src_path.first
+          when :last  then src_path.last
+          else
+            raise ArgumentError, "Unknown REF_ID_PATH_POSITION: #{ref_id_path_position}  "
+          end
+
+        file_row  = [ref_id]
+        file_row << file_name = File.basename(file)
+        file_row << File.size(file)
+        file_row << s3_path(file_name, src_path)
+
+        csv      << file_row
+      end
+    end
+  ensure
+    msg  = "Generated file '#{output_filename}' "
+    msg << "with #{file_count} files/rows "
+    msg << "organized in #{folder_count} folders."
+
+    log(:info) { msg } unless simulate?
+  end
+
+  def with_each_file(folders = top_subfolders, src_path: [], &block)
+    folders.each do |folder|
+      folder_name = File.basename(folder)
+      path        = src_path[0..-1]
+      path       << folder_name
+
+      files       = folder_files(folder)
+      subfolders  = top_subfolders(folder)
+
+      next if files.empty? && subfolders.empty? # skip
+
+      if files.any? && subfolders.any?
+        msg  = "Folder '#{folder}' contains both files and subfolders."
+        msg << "\nFor correctly tracking and handling file attachments, "
+        msg << "this is not supported."
+
+        raise ArgumentError, msg
+      end
+
+      unless files.empty?
+        folder_count!
+        file_count!(files.count)
+
+        files.each do |file|
+          yield(file, path) if block_given?
+        end
+      end
+
+      next if subfolders.empty?
+
+      with_each_file(
+        subfolders,
+        src_path: path,
+        &block
+      )
+    end
+  end
+
+  def s3_path(filename, path)
+    [
+      self.class::BASE_S3_PATH,
+      s3_subpath,
+      *path,
+      filename
+    ].compact.join('/')
+  end
+
+  def s3_subpath
+    options.dig(:output, :s3_path) ||
+      s3_subpath_const             ||
+      config.active_enviro
+  end
+
+  def s3_subpath_const
+    self.class::S3_SUBPATH if self.class.const_defined?(:S3_SUBPATH)
+  end
+
+  def top_subfolders(base_folder = input_base_folder)
+    Dir[
+      File.join(base_folder, "*")
+    ].select do |f|
+      File.directory?(f)
+    end
+  end
+
+  def folder_files(dir)
+    Dir[
+      File.join(dir, "*")
+    ].select do |f|
+      File.file?(f)
+    end
+  end
+
+  def output_filename
+    return unless input_folder_name
+
+    File.join(
+      config.active_enviro,
+      'sftp',
+      "#{input_folder_name}_files.csv"
+    )
+  end
+
+  def input_folder_name
+    @input_folder_name ||= File.basename(input_base_folder)
+  end
+
+  def input_base_folder
+    options.dig(:input, :folder).tap do |folder|
+      next if File.directory?(folder)
+
+      msg = "Expecting '#{folder}' to be a directory, but it isn't."
+      raise ArgumentError, msg
+    end
+  end
+end

data/lib/eco/api/usecases/default/utils.rb

@@ -16,3 +16,5 @@ require_relative 'utils/sort_csv_case'
 require_relative 'utils/group_csv_case'
 require_relative 'utils/merge_csv_case'
 require_relative 'utils/entries_to_csv_case'
+require_relative 'utils/track_files_case'
+require_relative 'utils/add_page_id_case'

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

@@ -0,0 +1,120 @@
+# usecases/graphql
+
+GraphQL-native use case base classes and helpers. All cases here work directly with
+`ecoportal-api-graphql` — no v2 REST layer, no ooze objects.
+
+---
+
+## Class hierarchy
+
+```
+Eco::API::Common::Loaders::UseCase                           (registration + launch)
+    ↓
+Eco::API::UseCases::GraphQL::Base                            ← universal GraphQL env
+    ├── GraphQL::Samples::Pages::Page::Base                  ← register-scoped pages
+    │       ├── GraphQL::Samples::Pages::OrgPage::Base       ← org-wide pages
+    │       └── your subclass (process_page, search_conf)
+    └── your subclass directly (custom scripts: exports, reports, one-offs)
+```
+
+Samples live under `samples/pages/` — NOT in the `graphql/` root. The root only
+has `base.rb`, `helpers.rb`, `utils.rb`, and `samples.rb`.
+
+---
+
+## Base — `graphql/base.rb`
+
+Universal GraphQL environment. Provides `graphql`, `session`, `options`, `config`,
+`simulate?`, `log`, `backup` via `Helpers::Base` (see `helpers/CLAUDE.md`).
+
+Override `process` to write your script:
+```ruby
+class MyCase < Eco::API::UseCases::GraphQL::Base
+  name 'my-case'
+  def process
+    graphql.currentOrganization.contractorEntities.each { |c| puts c.name }
+  end
+end
+```
+
+---
+
+## Pages — `samples/pages/`
+
+Page processing base cases. Follow the hierarchy: `page/base` → `org_page/base`.
+
+### `samples/pages/page/base.rb` — `Samples::Pages::Page::Base`
+
+For **register-scoped** page update workflows.
+
+**Class methods:** `register_id 'REG_ID'`, `batch_size 50` (default)
+
+**Override points:**
+- `process_page(page)` — **required** — transformation for one page
+- `search_conf` — optional — call `super` to keep register scope, then add filters
+
+**Protected helpers:** `update_page`, `skip(reason)`, `each_page`
+
+**KPI readers:** `total_pages`, `processed_pages`, `updated_pages`, `skipped_pages`, `failed_pages`
+
+**DSL (via `samples/pages/page/dsl.rb`):** `sc`, `in_register`, `state_is`, `external_id_eq`, `updated_since`
+
+```ruby
+class Custom::UseCase::UpdateStatus < Eco::API::UseCases::GraphQL::Samples::Pages::Page::Base
+  name 'update-status'
+  register_id 'REG_ABC'
+
+  def search_conf
+    super.filter(state_is(:active))
+  end
+
+  def process_page(page)
+    page.name = page.name.upcase
+    update_page(page)
+  end
+end
+```
+
+### `samples/pages/org_page/base.rb` — `Samples::Pages::OrgPage::Base`
+
+Inherits `Page::Base`. `search_conf` starts empty (org-wide, no register scope).
+Use for: archive sweeps, cross-register audits, bulk org operations.
+
+---
+
+## Samples — `graphql/samples/`
+
+Built-in ready-to-use case implementations:
+- `samples/location.rb` — location structure management cases
+- `samples/contractors.rb` — contractor entity cases
+
+See `samples/CLAUDE.md` for details.
+
+---
+
+## Helpers — `graphql/helpers/`
+
+Mixins providing domain-specific access patterns. See `helpers/CLAUDE.md`.
+
+---
+
+## Loader order in `graphql.rb`
+
+```ruby
+require 'graphql/helpers'   # environment mixins (graphql, session, simulate? etc.)
+require 'graphql/utils'     # utility modules (SFTP etc.)
+require 'graphql/base'      # GraphQL::Base — universal foundation
+require 'graphql/samples'   # sample cases: location, contractors, pages, ...
+  # └─ graphql/samples/pages.rb
+  #      └─ pages/page.rb        → page/dsl.rb, page/base.rb
+  #      └─ pages/org_page.rb    → org_page/dsl.rb, org_page/base.rb
+```
+
+Page base cases are in `samples/pages/` — NOT in the `graphql/` root.
+Custom org cases are NOT loaded here — they live in the implementation repo.
+
+## default/pages/
+
+CLI-integrated page use cases go in `default/pages/` (mirroring `default/locations/`
+and `default/people/`). Currently empty — add cases there when a pattern is common
+enough to expose to all org environments. See `default/pages.rb` for the convention.

data/lib/eco/api/usecases/graphql/compat/ooze_redirect/dirty_array.rb

@@ -0,0 +1,22 @@
+module Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  # Array subclass that calls the field's setter when elements are appended,
+  # ensuring GraphQL dirty-tracking fires on `fld.people_ids << value`.
+  class DirtyArray < Array
+    def initialize(field, data)
+      @field = field
+      super(Array(data))
+    end
+
+    def <<(value)
+      super
+      @field.people_ids = to_a
+      self
+    end
+
+    def push(*values)
+      super
+      @field.people_ids = to_a
+      self
+    end
+  end
+end