aspera-cli 4.27.1 → 4.27.3

data/lib/aspera/cli/plugins/faspex5.rb

@@ -5,6 +5,7 @@
 require 'aspera/schema/registry'
 require 'aspera/cli/plugins/oauth'
 require 'aspera/cli/extended_value'
+require 'aspera/cli/formatter'
 require 'aspera/transfer/result'
 require 'aspera/cli/special_values'
 require 'aspera/cli/wizard'
@@ -15,6 +16,8 @@ require 'aspera/nagios'
 require 'aspera/environment'
 require 'aspera/assert'
 require 'securerandom'
+require 'aspera/rainbow'
+using Rainbow
 
 module Aspera
   module Cli
@@ -35,7 +38,7 @@ module Aspera
             urls.each do |base_url|
               # Faspex is always HTTPS
               next unless base_url.start_with?('https://')
-              api = Rest.new(base_url: base_url, redirect_max: 1)
+              api = Rest::Client.new(base_url: base_url, redirect_max: 1)
               response = api.read(Api::Faspex::PATH_API_DETECT, ret: :resp)
               next unless response.code.start_with?('2') && response.body.strip.empty?
               # end is at -1, and subtract 1 for "/"
@@ -96,13 +99,6 @@ module Aspera
         option :shared_folder, description: 'Send package with files from shared folder'
         option :group_type,    description: 'Type of shared box', allowed: %i[shared_inboxes workgroups], default: :shared_inboxes
 
-        def initialize(**_)
-          super
-          options.parse_options!
-          # [Aspera::Api::Faspex]
-          @api_v5 = nil
-        end
-
         # if recipient is just an email, then convert to expected API hash : name and type
         def normalize_recipients(parameters, type)
           type = type.to_s
@@ -117,7 +113,7 @@ module Aspera
           parameters[type].map! do |recipient_data|
             # If just a string, make a general lookup and build expected name/type hash
             if recipient_data.is_a?(String)
-              matched = @api_v5.lookup_with_q('contacts', value: recipient_data, query: Rest.php_style({context: 'packages', type: recipient_types}))
+              matched = api_v5.lookup_with_q('contacts', value: recipient_data, query: Rest.php_style({context: 'packages', type: recipient_types}))
               recipient_data = {
                 name:           matched['name'],
                 recipient_type: matched['type']
@@ -132,7 +128,7 @@ module Aspera
         def wait_package_status(id, status_list: Api::Faspex::PACKAGE_TERMINATED)
           total_sent = false
           loop do
-            status = @api_v5.read("packages/#{id}/upload_details")
+            status = api_v5.read("packages/#{id}/upload_details")
             status['id'] = id
             # user asked to not follow
             return status if status_list.nil?
@@ -159,12 +155,12 @@ module Aspera
         def wait_for_job(job_id)
           result = nil
           loop do
-            result = @api_v5.read("jobs/#{job_id}", {type: :formatted})
+            result = api_v5.read("jobs/#{job_id}", {type: :formatted})
             break unless Api::Faspex::JOB_RUNNING.include?(result['status'])
-            RestParameters.instance.spinner_cb.call(result['status'])
+            Rest::Parameters.instance.spinner_cb.call(result['status'])
             sleep(0.5)
           end
-          RestParameters.instance.spinner_cb.call(action: :success)
+          Rest::Parameters.instance.spinner_cb.call(action: :success)
           return result
         end
 
@@ -185,21 +181,21 @@ module Aspera
             when *Api::Faspex::API_LIST_MAILBOX_TYPES then "#{box}/packages"
             else
               group_type = options.get_option(:group_type)
-              "#{group_type}/#{@api_v5.lookup_entity_by_field(entity: group_type, value: box)['id']}/packages"
+              "#{group_type}/#{api_v5.lookup_entity_by_field(entity: group_type, value: box)['id']}/packages"
             end
           # Merge default query with user-provided query: user values take precedence, but defaults are preserved
           user_query = query_read_delete(schema: Schema::Registry.query_params(Schema::Registry::FASPEX, 'packages'))
           merged_query = user_query.nil? ? query.dup : query.merge(user_query)
           # Extract `max` before the API call so callers can apply it after post-API filtering
-          max_items = merged_query.delete(RestList::MAX_ITEMS)&.to_i
-          list, total = @api_v5.list_entities_limit_offset_total_count(entity: entity, query: merged_query)
+          max_items = merged_query.delete(Rest::List::MAX_ITEMS)&.to_i
+          list, total = api_v5.list_entities_limit_offset_total_count(entity: entity, query: merged_query)
           return list.select(&filter), max_items, total
         end
 
         # Build query to get package recipients based on package info in case of shared inbox or workgroup recipient
         # @param package_id [String] the package id to get info from
         def recipient_query(package_id)
-          package_info = @api_v5.read("packages/#{package_id}")
+          package_info = api_v5.read("packages/#{package_id}")
           base_query = {}
           base_query['recipient_workgroup_id'] = package_info['recipients'].first['id'] if WORKGROUP_TYPES.include?(package_info['recipients'].first['recipient_type'])
           base_query['recipient_user_id'] = package_info['recipients'].first['id'] if package_info['recipients'].first['recipient_type'].eql?('user')
@@ -242,7 +238,7 @@ module Aspera
             # a single id was provided, or a list of ids
             package_ids = [package_ids] unless package_ids.is_a?(Array)
             Aspera.assert_array_all(package_ids, String) { 'Package id(s)' }
-            # packages = package_ids.map{|pkg_id|@api_v5.read("packages/#{pkg_id}")}
+            # packages = package_ids.map{|pkg_id|api_v5.read("packages/#{pkg_id}")}
             packages = package_ids.map { |pkg_id| {'id'=>pkg_id} }
           end
           result_transfer = []
@@ -257,12 +253,12 @@ module Aspera
             type:          Api::Faspex.box_type(box),
             transfer_type: Api::Faspex::TRANSFER_CONNECT
           }
-          # download_params[:recipient_workgroup_id] = @api_v5.lookup_entity_by_field(entity: options.get_option(:group_type), value: box)['id'] if !Api::Faspex::API_LIST_MAILBOX_TYPES.include?(box) && box != SpecialValues::ALL
+          # download_params[:recipient_workgroup_id] = api_v5.lookup_entity_by_field(entity: options.get_option(:group_type), value: box)['id'] if !Api::Faspex::API_LIST_MAILBOX_TYPES.include?(box) && box != SpecialValues::ALL
           packages.each do |package|
             pkg_id = package['id']
             formatter.display_status("Receiving package #{pkg_id}")
             # TODO: allow from sent as well ?
-            transfer_spec = @api_v5.call(
+            transfer_spec = api_v5.call(
               operation:    'POST',
               subpath:      "packages/#{pkg_id}/transfer_spec/download",
               query:        download_params.merge(recipient_query(pkg_id)),
@@ -285,10 +281,10 @@ module Aspera
 
         def package_send(parameters)
           # autofill recipient for public url
-          if @api_v5.pub_link_context&.key?('recipient_type') && !parameters.key?('recipients')
+          if api_v5.pub_link_context&.key?('recipient_type') && !parameters.key?('recipients')
             parameters['recipients'] = [{
-              name:           @api_v5.pub_link_context['name'],
-              recipient_type: @api_v5.pub_link_context['recipient_type']
+              name:           api_v5.pub_link_context['name'],
+              recipient_type: api_v5.pub_link_context['recipient_type']
             }]
           end
           PACKAGE_RECIPIENT_TYPES.each { |type| normalize_recipients(parameters, type) }
@@ -298,11 +294,11 @@ module Aspera
             transfer.user_transfer_spec.delete('content_protection')
             parameters['ear_enabled'] = true
           end
-          package = @api_v5.create('packages', parameters)
+          package = api_v5.create('packages', parameters)
           shared_folder = options.get_option(:shared_folder)
           if shared_folder.nil?
             # send from local files
-            transfer_spec = @api_v5.create(
+            transfer_spec = api_v5.create(
               "packages/#{package['id']}/transfer_spec/upload",
               {paths: transfer.source_list},
               query: {transfer_type: Api::Faspex::TRANSFER_CONNECT}
@@ -313,7 +309,7 @@ module Aspera
           else
             # send from remote shared folder
             if (m = Parser.percent_selector(shared_folder))
-              shared_folder = @api_v5.lookup_entity_by_field(
+              shared_folder = api_v5.lookup_entity_by_field(
                 entity: 'shared_folders',
                 field: m[:field],
                 value: m[:value]
@@ -321,7 +317,7 @@ module Aspera
             end
             transfer_request = {shared_folder_id: shared_folder, paths: transfer.source_list}
             # start remote transfer and get first status
-            result = @api_v5.create("packages/#{package['id']}/remote_transfer", transfer_request)
+            result = api_v5.create("packages/#{package['id']}/remote_transfer", transfer_request)
             result['id'] = package['id']
             unless result['status'].eql?('completed')
               formatter.display_status("Package #{package['id']}")
@@ -341,7 +337,7 @@ module Aspera
           Aspera.assert_type(filters, Hash)
           filters['basenames'] ||= []
           Aspera.assert_type(filters, Hash) { 'filters' }
-          max_items = query.delete(RestList::MAX_ITEMS)
+          max_items = query.delete(Rest::List::MAX_ITEMS)
           recursive = query.delete('recursive')
           use_paging = query.delete('paging') { true }
           if use_paging
@@ -356,7 +352,7 @@ module Aspera
           until folders_to_process.empty?
             path = folders_to_process.shift
             loop do
-              data, http = @api_v5.call(
+              data, http = api_v5.call(
                 operation:    'POST',
                 subpath:      browse_endpoint,
                 query:        query,
@@ -380,49 +376,49 @@ module Aspera
                 break if data['item_count'].eql?(0)
                 query['offset'] += data['item_count']
               end
-              RestParameters.instance.spinner_cb.call(all_items.count)
+              Rest::Parameters.instance.spinner_cb.call(all_items.count)
             end
             query.delete('iteration_token')
           end
-          RestParameters.instance.spinner_cb.call(action: :success)
+          Rest::Parameters.instance.spinner_cb.call(action: :success)
           return Result::ObjectList.new(all_items, total: total_count)
         end
 
         # Per-resource configuration for admin CRUD sub-trees.
-        # Keys mirror entity_list/show/create/modify/delete kwargs; extra_commands lists additional leaf commands.
+        # Keys mirror entity_list/show/create/modify/delete kwargs; extra_commands declares additional leaf commands: {name => command attributes}.
         # @return [Hash{Symbol => Hash}]
         RESOURCE_CONFIG = {
           accounts:            {
-            display_fields:        -> { Formatter.all_but('user_profile_data_attributes') },
-            extra_commands:        [:reset_password],
-            instance_arg_commands: {reset_password: {arguments: [{name: :contact_id, type: :identifier, lookup: ->(field, value, **) { res_lookup_id(:accounts, field, value) }}]}},
-            query_component:       Schema::Registry::FASPEX,
-            body_component:        Schema::Registry::FASPEX
+            display_fields:  Formatter.all_but('user_profile_data_attributes'),
+            extra_commands:  {reset_password: {description: 'Send password reset email to account', arguments: [{name: :account_id, type: :identifier, lookup: ->(field, value, **) { res_lookup_id(:accounts, field, value) }}]}},
+            query_component: Schema::Registry::FASPEX,
+            body_component:  Schema::Registry::FASPEX
           },
           alternate_addresses: {entity: 'configuration/alternate_addresses', query_component: Schema::Registry::FASPEX, body_component: Schema::Registry::FASPEX},
           contacts:            {query_component: Schema::Registry::FASPEX},
           distribution_lists:  {entity: 'account/distribution_lists', delete_style: 'ids', query_component: Schema::Registry::FASPEX, body_component: Schema::Registry::FASPEX},
           email_notifications: {id_as_arg: 'type', query_component: Schema::Registry::FASPEX},
           file_processing:     {
-            commands:       %i[next modify],
+            commands:       %i[modify],
+            extra_commands: {next: {description: 'List next files to process'}},
             body_component: Schema::Registry::FASPEX,
             is_singleton:   true
           },
           jobs:                {display_fields: %w[id job_name job_type status], query_component: Schema::Registry::FASPEX},
           metadata_profiles:   {entity: 'configuration/metadata_profiles', items_key: 'profiles', query_component: Schema::Registry::FASPEX, body_component: Schema::Registry::FASPEX},
           nodes:               {
-            extra_commands:        %i[browse],
-            instance_arg_commands: {
+            extra_commands:  {
               browse: {
-                arguments: [{name: :node_id, type: :identifier, lookup: :lookup_node_id},
-                            {name: :folder_path, type: String, mandatory: false, default: '/'}]
+                description: 'Browse files of node',
+                arguments:   [{name: :node_id, type: :identifier, lookup: :lookup_node_id},
+                              {name: :folder_path, mandatory: false, default: '/'}]
               }
             },
-            query_component:       Schema::Registry::FASPEX,
-            body_component:        Schema::Registry::FASPEX
+            query_component: Schema::Registry::FASPEX,
+            body_component:  Schema::Registry::FASPEX
           },
           oauth_clients:       {
-            display_fields:  -> { Formatter.all_but('public_key') },
+            display_fields:  Formatter.all_but('public_key'),
             api:             -> { Api::Faspex.new(root: Api::Faspex::PATH_AUTH, **Oauth.kwargs_from_options(options)) },
             list_query:      {'expand': true, 'no_api_path': true, 'client_types[]': 'public'},
             query_component: Schema::Registry::FASPEX,
@@ -446,7 +442,7 @@ module Aspera
         def res_exec_args(res_sym)
           cfg = RESOURCE_CONFIG.fetch(res_sym, {})
           {
-            api:             resource_config_value(cfg, :api) || @api_v5,
+            api:             resource_config_value(cfg, :api) || api_v5,
             entity:          resource_config_value(cfg, :entity) || res_sym.to_s,
             items_key:       resource_config_value(cfg, :items_key),
             delete_style:    resource_config_value(cfg, :delete_style),
@@ -461,7 +457,7 @@ module Aspera
 
         # admin > nodes — lookup node id by field/value
         def lookup_node_id(field, value, **)
-          @api_v5.lookup_entity_by_field(entity: 'nodes', field: field, value: value)['id']
+          api_v5.lookup_entity_by_field(entity: 'nodes', field: field, value: value)['id']
         end
 
         # Lookup id for a RESOURCE_CONFIG resource by field/value.
@@ -470,7 +466,7 @@ module Aspera
           entity      = resource_config_value(cfg, :entity) || res_sym.to_s
           items_key   = resource_config_value(cfg, :items_key)
           res_id_query = resource_config_value(cfg, :res_id_query) || :default
-          @api_v5.lookup_entity_by_field(entity: entity, value: value, field: field, items_key: items_key, query: res_id_query)['id']
+          api_v5.lookup_entity_by_field(entity: entity, value: value, field: field, items_key: items_key, query: res_id_query)['id']
         end
 
         # Dynamically define lookup methods for admin resources (used by crud_commands)
@@ -482,78 +478,86 @@ module Aspera
 
         # --- DSL ---
 
-        # Commands that need @api_v5 carry setup: :setup_api_v5.
-        # :health and :postprocessing work without authentication, so they have no setup.
+        # :health and :postprocessing work without authentication: they do not use api_v5.
         command :health,         description: 'Check Faspex 5 health'
-        command :version,        description: 'Show Faspex 5 version',             setup: :setup_api_v5, action: -> { Result::SingleObject.new(@api_v5.read('version')) }
-        command :bearer_token,   description: 'Show OAuth bearer token',           setup: :setup_api_v5, action: -> { Result::Text.new(@api_v5.oauth.authorization) }
-        command :packages, description: 'Manage packages', setup: :setup_api_v5
+        command :version,        description: 'Show Faspex 5 version', action: ->(**) { Result::SingleObject.new(api_v5.read('version')) }
+        command :bearer_token,   description: 'Show OAuth bearer token', action: ->(**) { Result::Text.new(api_v5.oauth.authorization) }
+        # Package id argument; with a public link to a package, setup_package_id provides it instead
+        PACKAGE_ID_ARG = [{name: :package_id, type: :identifier}].freeze
+        private_constant :PACKAGE_ID_ARG
+        command :packages, description: 'Manage packages'
         commands_under :packages do
           command :list,   description: 'List packages',
             arguments: [{name: :filter, mandatory: false, default: nil, type: Proc}]
           command :send,   description: 'Send a package', transfer_paths: :send,
-            arguments: [{name: :data, type: Hash, schema: Schema::Registry.req_body(Schema::Registry::FASPEX, 'packages.post')}],
-            action: ->(data:, **) { package_send(data) }
-          command :show,   description: 'Show a package', setup: :setup_package_id,
-            action: ->(package_id:, **) { Result::SingleObject.new(@api_v5.read("packages/#{package_id}")) }
+            arguments: [{name: :package, type: Hash, schema: Schema::Registry.req_body(Schema::Registry::FASPEX, 'packages.post')}],
+            action: ->(package:, **) { package_send(package) }
+          command :show,   description: 'Show a package', setup: :setup_package_id, arguments: PACKAGE_ID_ARG,
+            action: ->(package_id:, **) { Result::SingleObject.new(api_v5.read("packages/#{package_id}")) }
           command :browse, description: 'Browse package files', setup: :setup_package_id,
-            arguments: [{name: :folder_path, type: String, mandatory: false, default: '/'}],
+            arguments: PACKAGE_ID_ARG + [{name: :folder_path, mandatory: false, default: '/'}],
             action: ->(folder_path:, package_id:, **) { browse_folder("packages/#{package_id}/files/#{Api::Faspex.box_type(options.get_option(:box))}", recipient_query(package_id), folder_path: folder_path) }
           command :status, description: 'Wait for package status', setup: :setup_package_id,
-            arguments: [{name: :status_list, type: Array, mandatory: false, default: nil}],
+            arguments: PACKAGE_ID_ARG + [{name: :status_list, type: Array, mandatory: false, default: nil}],
             action: ->(status_list:, package_id:, **) { Result::SingleObject.new(wait_package_status(package_id, status_list: status_list)) }
-          command :delete, description: 'Delete packages', setup: :setup_package_id
-          command :receive, description: 'Receive a package', setup: :setup_package_id, transfer_paths: :receive,
+          command :delete, description: 'Delete packages', setup: :setup_package_id, arguments: PACKAGE_ID_ARG
+          command :receive, description: 'Receive a package', setup: :setup_package_id, transfer_paths: :receive, arguments: PACKAGE_ID_ARG,
             action: ->(package_id:, **) { package_receive(package_id) }
-          command(:file_processing, description: 'Show file processing status', setup: :setup_package_id, action: lambda do |package_id:, **|
-            result, count = @api_v5.list_entities_limit_offset_total_count(entity: "packages/#{package_id}/file_statuses", items_key: 'files')
+          command(:file_processing, description: 'Show file processing status', setup: :setup_package_id, arguments: PACKAGE_ID_ARG, action: lambda do |package_id:, **|
+            result, count = api_v5.list_entities_limit_offset_total_count(entity: "packages/#{package_id}/file_statuses", items_key: 'files')
             Result::ObjectList.new(result, total: count)
           end)
         end
-        command :admin,          description: 'Administer Faspex 5',               setup: :setup_api_v5
-        command :user,           description: 'Manage current user',               setup: :setup_api_v5
-        command :shared_folders, description: 'Browse shared folders',             setup: :setup_api_v5
-        command :gateway,        description: 'Start Faspex 4 gateway emulation',  setup: :setup_api_v5,
+        command :admin,          description: 'Administer Faspex 5'
+        command :user,           description: 'Manage current user'
+        command :shared_folders, description: 'Browse shared folders'
+        command :gateway,        description: 'Start Faspex 4 gateway emulation',
           arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
         command :postprocessing, description: 'Start Faspex 4 post-processing server',
           arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
-        command :invitations,    description: 'Manage invitations', setup: :setup_api_v5
+        command :invitations,    description: 'Manage invitations'
 
         commands_under :invitations do
           command :create, description: 'Create an invitation',
-            arguments: [{name: :input_data, type: Hash, bulk: true}]
-          command :resend, description: 'Resend an invitation',
-            arguments: [{name: :invitation_id, type: :identifier}]
+            arguments: [{name: :invitation, type: Hash, bulk: true}]
+          command(
+            :resend, description: 'Resend an invitation',
+            arguments: [{name: :invitation_id, type: :identifier}],
+            action: lambda do |invitation_id:, **|
+              api_v5.create("invitations/#{invitation_id}/resend", nil)
+              Result::Status.new('Invitation resent')
+            end
+          )
           crud_commands entity: 'invitations',
-            api:            :@api_v5,
+            api:            :api_v5,
             operations:     Operations::ALL - %i[create],
             items_key:      'invitations',
             display_fields: %w[id public recipient_type recipient_name email_address]
         end
 
         commands_under :user do
-          command :account, description: 'Show account information', action: -> { Result::SingleObject.new(@api_v5.read('account', query_read_delete)) }
+          command :account, description: 'Show account information', action: ->(**) { Result::SingleObject.new(api_v5.read('account', query_read_delete)) }
           command :profile, description: 'Manage user profile'
         end
 
         commands_under %i[user profile] do
-          command :show, description: 'Show user profile', action: -> { Result::SingleObject.new(@api_v5.read('account/preferences')) }
+          command :show, description: 'Show user profile', action: ->(**) { Result::SingleObject.new(api_v5.read('account/preferences')) }
           command(
             :modify,
             description: 'Modify user profile',
-            arguments: [{name: :properties, type: Hash}],
-            action: lambda do |properties:, **|
-              @api_v5.update('account/preferences', properties)
+            arguments: [{name: :profile, type: Hash}],
+            action: lambda do |profile:, **|
+              api_v5.update('account/preferences', profile)
               Result::Status.new('modified')
             end
           )
         end
 
         commands_under :shared_folders do
-          command :list,   description: 'List shared folders', action: -> { Result::ObjectList.new(@api_v5.read('shared_folders')['shared_folders']) }
+          command :list,   description: 'List shared folders', action: ->(**) { Result::ObjectList.new(api_v5.read('shared_folders')['shared_folders']) }
           command :browse, description: 'Browse a shared folder',
             arguments: [{name: :shared_folder_id, type: :identifier, lookup: :lookup_shared_folder_id},
-                        {name: :folder_path, type: String, mandatory: false, default: '/'}]
+                        {name: :folder_path, mandatory: false, default: '/'}]
         end
 
         # admin sub-tree: fixed commands + all ADMIN_RESOURCES with their sub-commands
@@ -561,21 +565,26 @@ module Aspera
           command :configuration, description: 'Manage Faspex 5 configuration'
           command :smtp,          description: 'Manage SMTP configuration'
           command :events,        description: 'List events'
-          command :clean_deleted, description: 'Clean deleted packages',
-            arguments: [{name: :input_data, type: Hash, mandatory: false, default: {}}]
+          command(
+            :clean_deleted, description: 'Clean deleted packages',
+            arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}],
+            action: lambda do |parameters: {}, **|
+              parameters = api_v5.read('configuration').slice('days_before_deleting_package_records') if parameters.empty?
+              Result::SingleObject.new(api_v5.create('internal/packages/clean_deleted', parameters))
+            end
+          )
           Api::Faspex::ADMIN_RESOURCES.each do |res|
             cfg          = RESOURCE_CONFIG.fetch(res, {})
-            extra        = cfg[:extra_commands] || []
-            ia_cmds      = cfg[:instance_arg_commands] || {}
+            extra        = cfg[:extra_commands] || {}
             is_singleton = cfg[:is_singleton] || false
             entity_path  = cfg[:entity] || res.to_s
             crud_ops     = ((cfg[:commands] || Operations::ALL) - %i[list]) & Operations::ALL
 
-            command res, description: "Manage #{res.to_s.tr('_', ' ')}"
-            commands_under(res) do
+            command res, description: "Manage #{entity_noun(res, singular: false)}"
+            commands_under res do
               # List is handled with Faspex 5 pagination (item_list_with_total)
               unless is_singleton
-                list_kwargs = {description: 'List'}
+                list_kwargs = {description: operation_description(:list, entity_noun(entity_path))}
                 list_kwargs[:query_schema] = Schema::Registry.query_params(cfg[:query_component], entity_path) if cfg[:query_component]
                 command :list, **list_kwargs
               end
@@ -594,9 +603,8 @@ module Aspera
               )
 
               # Extra commands (e.g. browse, reset_password, next)
-              extra.each do |c|
-                ia = ia_cmds[c] || {}
-                command c, description: c.to_s.tr('_', ' ').capitalize, **ia
+              extra.each do |name, attrs|
+                command name, **attrs
               end
             end
           end
@@ -612,19 +620,19 @@ module Aspera
         # entity: :sf_entity is resolved at runtime from ctx (injected by setup_admin_nodes_shared_folders).
         commands_under %i[admin nodes shared_folders] do
           crud_commands entity: :sf_entity,
-            api: :@api_v5,
+            api: :api_v5,
             name: 'shared folder',
             lookup: :lookup_sf_id,
             items_key: 'shared_folders'
-          command :user, description: 'Custom access users',
-            arguments: [{name: :sf_id, type: :identifier, lookup: :lookup_sf_id}],
+          command :user, description: 'Manage custom access users',
+            arguments: [{name: :shared_folder_id, type: :identifier, lookup: :lookup_sf_id}],
             setup: :setup_admin_nodes_shared_folders_user
         end
 
         # admin > nodes > shared_folders > user sub-tree (custom access users)
         # entity: :user_path is resolved at runtime from ctx (injected by setup_admin_nodes_shared_folders_user).
         commands_under %i[admin nodes shared_folders user] do
-          crud_commands entity: :user_path, api: :@api_v5, name: 'custom access user', lookup: :lookup_sf_user_id, items_key: 'users'
+          crud_commands entity: :user_path, api: :api_v5, name: 'custom access user', lookup: :lookup_sf_user_id, items_key: 'users'
         end
 
         # `members` and `saml_groups`
@@ -632,41 +640,48 @@ module Aspera
         CRUD_NO_LIST = %i[create modify delete show].freeze
 
         RES_SINGULAR = {shared_inboxes: :shared_inbox, workgroups: :workgroup}.freeze
-        private_constant :RES_SINGULAR
+        # Access levels of members, per resource
+        MEMBER_ACCESS = {
+          shared_inboxes: %i[submit_only standard shared_inbox_admin].freeze,
+          workgroups:     %i[standard workgroup_admin].freeze
+        }.freeze
+        private_constant :RES_SINGULAR, :MEMBER_ACCESS
 
         # admin > shared_inboxes|workgroups > members|saml_groups|invite_external_collaborator:
         # res_id consumed via arguments:(:identifier) + lookup:, builds res_instance_path for all children
         %i[shared_inboxes workgroups].each do |res|
-          lookup_res_id = ->(field, value, **) { @api_v5.lookup_entity_by_field(entity: res.to_s, field: field, value: value, query: {'all': true})['id'] }
+          lookup_res_id = ->(field, value, **) { api_v5.lookup_entity_by_field(entity: res.to_s, field: field, value: value, query: {'all': true})['id'] }
           commands_under [:admin, res] do
-            command :members, description: 'Members',
+            command :members, description: 'Manage members',
               arguments: [{name: :"#{RES_SINGULAR[res]}_id", type: :identifier, lookup: lookup_res_id}],
               setup: :"setup_admin_#{res}_instance"
-            command :saml_groups, description: 'Saml groups',
+            command :saml_groups, description: 'Manage SAML groups',
               arguments: [{name: :"#{RES_SINGULAR[res]}_id", type: :identifier, lookup: lookup_res_id}],
               setup: :"setup_admin_#{res}_instance"
             command :invite_external_collaborator, description: 'Invite external collaborator',
               arguments: [{name: :"#{RES_SINGULAR[res]}_id", type: :identifier, lookup: lookup_res_id},
-                          {name: :input_data, type: Hash}]
+                          {name: :collaborator, type: Hash}]
           end
 
           commands_under [:admin, res, :members] do
             CRUD_NO_SHOW.each do |c|
               args =
                 if c.eql?(:create)
-                  {arguments: [{name: :users, bulk: true}, {name: :access, mandatory: false, default: :standard}]}
+                  {arguments: [{name: :users, bulk: true}, {name: :access, allowed: MEMBER_ACCESS[res], mandatory: false, default: :standard}]}
+                elsif c.eql?(:modify)
+                  {arguments: [{name: :member_id, type: :identifier, lookup: :"lookup_#{res}_members_id"}, {name: :member, type: Hash}]}
                 elsif Operations::INSTANCE.include?(c)
                   {arguments: [{name: :member_id, type: :identifier, lookup: :"lookup_#{res}_members_id"}]}
                 else
                   {}
                 end
-              command c, description: c.to_s.capitalize, **args
+              command c, description: operation_description(c, 'member'), **args
             end
           end
 
           commands_under [:admin, res, :saml_groups] do
             crud_commands entity: :saml_groups_path,
-              api: :@api_v5,
+              api: :api_v5,
               name: 'SAML group',
               operations: CRUD_NO_SHOW,
               lookup: :"lookup_#{res}_saml_groups_id",
@@ -675,57 +690,51 @@ module Aspera
         end
 
         commands_under %i[admin configuration] do
-          command :show, description: 'Show configuration', action: -> { Result::SingleObject.new(@api_v5.read('configuration')) }
+          command :show, description: 'Show configuration', action: ->(**) { Result::SingleObject.new(api_v5.read('configuration')) }
           command :modify, description: 'Modify configuration',
-            arguments: [{name: :input_data, type: Hash}],
-            action: ->(input_data:, **) { Result::SingleObject.new(@api_v5.update('configuration', input_data)) }
+            arguments: [{name: :configuration, type: Hash}],
+            action: ->(configuration:, **) { Result::SingleObject.new(api_v5.update('configuration', configuration)) }
         end
 
         commands_under %i[admin smtp] do
-          command :show, description: 'Show SMTP configuration', action: -> { Result::SingleObject.new(@api_v5.read('configuration/smtp')) }
+          command :show, description: 'Show SMTP configuration', action: ->(**) { Result::SingleObject.new(api_v5.read('configuration/smtp')) }
           command :create, description: 'Create SMTP configuration',
-            arguments: [{name: :input_data, type: Hash}],
-            action: ->(input_data:, **) { Result::SingleObject.new(@api_v5.create('configuration/smtp', input_data)) }
+            arguments: [{name: :smtp, type: Hash}],
+            action: ->(smtp:, **) { Result::SingleObject.new(api_v5.create('configuration/smtp', smtp)) }
           command :modify, description: 'Modify SMTP configuration',
-            arguments: [{name: :input_data, type: Hash}],
-            action: ->(input_data:, **) { Result::SingleObject.new(@api_v5.update('configuration/smtp', input_data)) }
+            arguments: [{name: :smtp, type: Hash}],
+            action: ->(smtp:, **) { Result::SingleObject.new(api_v5.update('configuration/smtp', smtp)) }
           command(
             :delete, description: 'Delete SMTP configuration',
-            action: lambda do
-              @api_v5.delete('configuration/smtp')
+            action: lambda do |**|
+              api_v5.delete('configuration/smtp')
               Result::Status.new('SMTP configuration deleted')
             end
           )
           command :test, description: 'Test SMTP configuration',
-            arguments: [{name: :test_data, type: nil}]
+            arguments: [{name: :recipient}]
         end
 
         commands_under %i[admin events] do
           command(
             :application, description: 'List application events',
-            action: lambda do
-              list, total = @api_v5.list_entities_limit_offset_total_count(entity: 'application_events', query: query_read_delete(schema: Schema::Registry.query_params(Schema::Registry::FASPEX, 'application_events')))
+            action: lambda do |**|
+              list, total = api_v5.list_entities_limit_offset_total_count(entity: 'application_events', query: query_read_delete(schema: Schema::Registry.query_params(Schema::Registry::FASPEX, 'application_events')))
               Result::ObjectList.new(list, total: total, fields: %w[event_type created_at application user.name])
             end
           )
           command(
             :webhook, description: 'List webhook events',
-            action: lambda do
-              list, total = @api_v5.list_entities_limit_offset_total_count(entity: 'all_webhooks_events', query: query_read_delete(schema: Schema::Registry.query_params(Schema::Registry::FASPEX, 'all_webhooks_events')), items_key: 'events')
+            action: lambda do |**|
+              list, total = api_v5.list_entities_limit_offset_total_count(entity: 'all_webhooks_events', query: query_read_delete(schema: Schema::Registry.query_params(Schema::Registry::FASPEX, 'all_webhooks_events')), items_key: 'events')
               Result::ObjectList.new(list, total: total)
             end
           )
         end
 
-        # admin > clean_deleted handler (leaf, no sub-commands)
-        define_action_method(%i[admin clean_deleted]) do |input_data: {}, **|
-          input_data = @api_v5.read('configuration').slice('days_before_deleting_package_records') if input_data.empty?
-          Result::SingleObject.new(@api_v5.create('internal/packages/clean_deleted', input_data))
-        end
-
         # admin > <resource> > list
         Api::Faspex::ADMIN_RESOURCES.each do |res|
-          define_action_method([:admin, res, :list]) do
+          define_action_method([:admin, res, :list]) do |**|
             args = res_exec_args(res)
             # Special case: email_notifications list returns a fixed value list
             next Result::ValueList.new(Api::Faspex::EMAIL_NOTIF_LIST, name: 'email_id') if res.eql?(:email_notifications)
@@ -740,9 +749,9 @@ module Aspera
           end
         end
 
-        def action_admin_smtp_test(test_data:, **)
-          test_data = {test_email_recipient: test_data} if test_data.is_a?(String)
-          creation = @api_v5.create('configuration/smtp/test', test_data)
+        def action_admin_smtp_test(recipient:, **)
+          recipient = {test_email_recipient: recipient} if recipient.is_a?(String)
+          creation = api_v5.create('configuration/smtp/test', recipient)
           result = wait_for_job(creation['job_id'])
           begin
             result['serialized_args'] = JSON.parse(result['serialized_args'])
@@ -753,15 +762,15 @@ module Aspera
         end
 
         # admin > accounts > reset_password
-        def action_admin_accounts_reset_password(contact_id:, **)
-          @api_v5.create("accounts/#{contact_id}/reset_password", {})
+        def action_admin_accounts_reset_password(account_id:, **)
+          api_v5.create("accounts/#{account_id}/reset_password", {})
           Result::Status.new('password reset, user shall check email')
         end
 
         # admin > file_processing > next
-        def action_admin_file_processing_next
+        def action_admin_file_processing_next(**)
           args = res_exec_args(:file_processing)
-          result, count = @api_v5.list_entities_limit_offset_total_count(entity: args[:entity], operation: 'POST', items_key: 'files')
+          result, count = api_v5.list_entities_limit_offset_total_count(entity: args[:entity], operation: 'POST', items_key: 'files')
           Result::ObjectList.new(result, total: count)
         end
 
@@ -778,18 +787,18 @@ module Aspera
         # Lookup shared folder id by field/value within a node's shared_folders entity.
         # sf_entity is in ctx from setup_admin_nodes_shared_folders (Phase A of parent).
         def lookup_sf_id(field, value, sf_entity:, **)
-          @api_v5.lookup_entity_by_field(entity: sf_entity, items_key: 'shared_folders', field: field, value: value)['id']
+          api_v5.lookup_entity_by_field(entity: sf_entity, items_key: 'shared_folders', field: field, value: value)['id']
         end
 
         # Lookup custom access user id by field/value within a shared folder's users entity.
         # user_path is in ctx from setup_admin_nodes_shared_folders_user (Phase A of parent).
         def lookup_sf_user_id(field, value, user_path:, **)
-          @api_v5.lookup_entity_by_field(entity: user_path, items_key: 'users', field: field, value: value)['id']
+          api_v5.lookup_entity_by_field(entity: user_path, items_key: 'users', field: field, value: value)['id']
         end
 
-        # admin > nodes > shared_folders > user — sf_id: already in ctx via arguments: on the :user command
-        def setup_admin_nodes_shared_folders_user(sf_entity:, sf_id:, **)
-          {user_path: "#{sf_entity}/#{sf_id}/custom_access_users"}
+        # admin > nodes > shared_folders > user — shared_folder_id: already in ctx via arguments: on the :user command
+        def setup_admin_nodes_shared_folders_user(sf_entity:, shared_folder_id:, **)
+          {user_path: "#{sf_entity}/#{shared_folder_id}/custom_access_users"}
         end
 
         # admin > shared_inboxes|workgroups — res_id: already in ctx via arguments: on the :members|:saml_groups command
@@ -810,7 +819,7 @@ module Aspera
           users = [users] unless users.is_a?(Array)
           users.map do |user|
             if (m = Parser.percent_selector(user))
-              @api_v5.lookup_entity_by_field(entity: 'accounts', field: m[:field], value: m[:value], query: Rest.php_style({type: ACCOUNT_TYPES}))['id']
+              api_v5.lookup_entity_by_field(entity: 'accounts', field: m[:field], value: m[:value], query: Rest.php_style({type: ACCOUNT_TYPES}))['id']
             else
               user
             end
@@ -822,11 +831,11 @@ module Aspera
         %i[shared_inboxes workgroups].each do |res|
           define_method(:"lookup_#{res}_members_id") do |field, value, res_instance_path:, **|
             res_path = "#{res_instance_path}/members"
-            @api_v5.lookup_entity_by_field(entity: res_path, field: field, value: value, query: Rest.php_style({type: %w[user]}))['user_id']
+            api_v5.lookup_entity_by_field(entity: res_path, field: field, value: value, query: Rest.php_style({type: %w[user]}))['user_id']
           end
           define_method(:"lookup_#{res}_saml_groups_id") do |field, value, res_instance_path:, **|
             res_path = "#{res_instance_path}/saml_groups"
-            @api_v5.lookup_entity_by_field(entity: res_path, field: field, value: value, query: Rest.php_style({type: %w[user]}))['user_id']
+            api_v5.lookup_entity_by_field(entity: res_path, field: field, value: value, query: Rest.php_style({type: %w[user]}))['user_id']
           end
         end
 
@@ -834,52 +843,52 @@ module Aspera
         # (saml_groups CRUD is handled by crud_commands)
         %i[shared_inboxes workgroups].each do |res|
           define_action_method([:admin, res, :members, :list]) do |res_instance_path:, **|
-            entity_list(api: @api_v5, entity: "#{res_instance_path}/members", items_key: 'members')
+            entity_list(api: api_v5, entity: "#{res_instance_path}/members", items_key: 'members')
           end
 
-          define_action_method([:admin, res, :members, :modify]) do |res_instance_path:, **kwargs|
-            entity_modify(api: @api_v5, entity: "#{res_instance_path}/members", id: kwargs[:member_id])
+          define_action_method([:admin, res, :members, :modify]) do |res_instance_path:, member_id:, member:, **|
+            entity_modify(api: api_v5, entity: "#{res_instance_path}/members", id: member_id, data: member)
           end
 
           define_action_method([:admin, res, :members, :delete]) do |res_instance_path:, **kwargs|
-            entity_delete(api: @api_v5, entity: "#{res_instance_path}/members", id: kwargs[:member_id])
+            entity_delete(api: api_v5, entity: "#{res_instance_path}/members", id: kwargs[:member_id])
           end
 
           define_action_method([:admin, res, :members, :create]) do |users:, access:, res_instance_path:, **|
             res_path = "#{res_instance_path}/members"
             resolved = resolve_member_user_ids(users)
-            input_data = [{user: resolved.map { |u| {id: u, access: access} }}]
-            entity_create(api: @api_v5, entity: res_path, input_data: input_data)
+            entity_create(api: api_v5, entity: res_path, data: {user: resolved.map { |u| {id: u, access: access} }})
           end
         end
 
         # admin > shared_inboxes|workgroups > invite_external_collaborator
         %i[shared_inboxes workgroups].each do |res|
-          define_action_method([:admin, res, :invite_external_collaborator]) do |input_data:, **kwargs|
+          define_action_method([:admin, res, :invite_external_collaborator]) do |collaborator:, **kwargs|
             res_instance_path = "#{res}/#{kwargs[:"#{RES_SINGULAR[res]}_id"]}"
-            result = @api_v5.create("#{res_instance_path}/external_collaborator", input_data)
+            result = api_v5.create("#{res_instance_path}/external_collaborator", collaborator)
             formatter.display_status(result['message'])
-            Result::SingleObject.new(@api_v5.lookup_entity_by_field(entity: "#{res_instance_path}/members", items_key: 'members', value: input_data['email_address'], query: {}))
+            Result::SingleObject.new(api_v5.lookup_entity_by_field(entity: "#{res_instance_path}/members", items_key: 'members', value: collaborator['email_address'], query: {}))
           end
         end
 
-        # --- root setup ---
+        # --- API ---
 
-        # Build @api_v5 for all commands that need it (all except :health and :postprocessing).
-        # @return [Hash] empty ctx (state stored in @api_v5)
-        def setup_api_v5(**)
-          return {} if @api_v5
+        # Faspex 5 API, built from CLI options on first use.
+        # @return [Api::Faspex]
+        def api_v5
+          return @api_v5 if @api_v5
           @api_v5 = Api::Faspex.new(**Oauth.kwargs_from_options(options))
           # in case user wants to use HTTPGW tell transfer agent how to get address
           transfer.httpgw_url_cb = lambda { @api_v5.read('account')['gateway_url'] }
-          {}
+          @api_v5
         end
 
-        # Setup for package sub-commands that need an id: resolves package_id from pub_link or argument.
-        # @return [Hash] ctx key: package_id
+        # Setup for package sub-commands that need an id: with a public link to a package, the id comes from the link.
+        # Leaf setup runs before argument resolution: the declared package_id argument is then not read.
+        # @return [Hash] ctx key: package_id, or empty (package_id is read from the command line)
         def setup_package_id(**)
-          package_id = @api_v5.pub_link_context&.key?('package_id') ? @api_v5.pub_link_context['package_id'] : options.instance_identifier
-          {package_id: package_id}
+          return {} unless api_v5.pub_link_context&.key?('package_id')
+          {package_id: api_v5.pub_link_context['package_id']}
         end
 
         def action_packages_list(filter: nil, **)
@@ -895,7 +904,7 @@ module Aspera
           ids = package_id.is_a?(Array) ? package_id : [package_id]
           Aspera.assert_array_all(ids, String) { 'Package id(s)' }
           # API returns 204, empty on success
-          @api_v5.call(
+          api_v5.call(
             operation:    'DELETE',
             subpath:      'packages',
             content_type: Mime::JSON,
@@ -907,10 +916,10 @@ module Aspera
 
         # --- handlers ---
 
-        def action_health
+        def action_health(**)
           nagios = Nagios.new
           begin
-            data, http = Rest.new(base_url: options.get_option(:url, mandatory: true))
+            data, http = Rest::Client.new(base_url: options.get_option(:url, mandatory: true))
               .read('health', ret: :both)
             data.each do |k, v|
               nagios.add_ok(k, v.to_s)
@@ -925,7 +934,7 @@ module Aspera
         # Lookup a shared folder id by field/value.
         # Called via lookup: :lookup_shared_folder_id on the shared_folders > browse command.
         def lookup_shared_folder_id(field, value, **)
-          all = @api_v5.read('shared_folders')['shared_folders']
+          all = api_v5.read('shared_folders')['shared_folders']
           matches = all.select { |i| i[field].eql?(value) }
           Aspera.assert(!matches.empty?) { "no match for #{field} = #{value}" }
           Aspera.assert(matches.length == 1) { "multiple matches for #{field} = #{value}" }
@@ -933,7 +942,7 @@ module Aspera
         end
 
         def action_shared_folders_browse(folder_path:, shared_folder_id:, **)
-          all_shared_folders = @api_v5.read('shared_folders')['shared_folders']
+          all_shared_folders = api_v5.read('shared_folders')['shared_folders']
           node = all_shared_folders.find { |i| i['id'].eql?(shared_folder_id) }
           Aspera.assert(!node.nil?) { "No such shared folder id #{shared_folder_id}" }
           browse_folder("nodes/#{node['node_id']}/shared_folders/#{shared_folder_id}/browse", {}, folder_path: folder_path)
@@ -941,15 +950,10 @@ module Aspera
 
         # invitations sub-handlers
 
-        def action_invitations_resend(invitation_id:, **)
-          @api_v5.create("invitations/#{invitation_id}/resend", nil)
-          Result::Status.new('Invitation resent')
-        end
-
-        def action_invitations_create(input_data:, **)
-          bulk_result(input_data, command: :create) do |params|
+        def action_invitations_create(invitation:, **)
+          bulk_result(invitation, command: :create) do |params|
             endpoint = params.key?('recipient_name') ? 'public_invitations' : 'invitations'
-            @api_v5.create(endpoint, params)
+            api_v5.create(endpoint, params)
           end
         end
 
@@ -959,7 +963,7 @@ module Aspera
           uri = URI.parse(parameters.delete(:url) { WebServerSimple::DEFAULT_URL })
           server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
           Aspera.assert(parameters.except(*WebServerSimple::PARAMS).empty?) { "unexpected parameters: #{parameters.except(*WebServerSimple::PARAMS).keys}" }
-          server.mount(uri.path, Faspex4GWServlet, @api_v5, nil)
+          server.mount(uri.path, Faspex4GWServlet, api_v5, nil)
           server.start
           Result::Status.new('Gateway terminated')
         end
@@ -974,12 +978,11 @@ module Aspera
           server.start
           Result::Status.new('Gateway terminated')
         end
-        SHARED_INBOX_MEMBER_LEVELS = %i[submit_only standard shared_inbox_admin].freeze
         ACCOUNT_TYPES = %w{local_user saml_user self_registered_user external_user}.freeze
         WORKGROUP_TYPES = %w{workgroup shared_inbox}.freeze
         CONTACT_TYPES = (WORKGROUP_TYPES + %w{distribution_list user external_user}).freeze
         PACKAGE_RECIPIENT_TYPES = %i{recipients private_recipients notified_on_upload notified_on_download notified_on_receipt}
-        private_constant :SHARED_INBOX_MEMBER_LEVELS, :ACCOUNT_TYPES, :CONTACT_TYPES, :PACKAGE_RECIPIENT_TYPES,
+        private_constant :ACCOUNT_TYPES, :CONTACT_TYPES, :PACKAGE_RECIPIENT_TYPES,
           :CRUD_NO_SHOW, :CRUD_NO_LIST
       end
     end