aspera-cli 4.15.0 → 4.17.0

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

@@ -4,23 +4,26 @@ require 'aspera/cli/plugins/node'
 require 'aspera/cli/plugins/ats'
 require 'aspera/cli/basic_auth_plugin'
 require 'aspera/cli/transfer_agent'
-require 'aspera/fasp/agent_node'
-require 'aspera/fasp/transfer_spec'
-require 'aspera/aoc'
-require 'aspera/node'
+require 'aspera/agent/node'
+require 'aspera/transfer/spec'
+require 'aspera/api/aoc'
+require 'aspera/api/node'
 require 'aspera/persistency_action_once'
 require 'aspera/id_generator'
+require 'aspera/assert'
 require 'securerandom'
 require 'date'
 
 module Aspera
   module Cli
     module Plugins
-      class Aoc < Aspera::Cli::BasicAuthPlugin
+      class Aoc < Cli::BasicAuthPlugin
         AOC_PATH_API_CLIENTS = 'admin/api-clients'
         # default redirect for AoC web auth
-        DEFAULT_REDIRECT = 'http://localhost:12345'
-        private_constant :AOC_PATH_API_CLIENTS, :DEFAULT_REDIRECT
+        REDIRECT_LOCALHOST = 'http://localhost:12345'
+        # OAuth methods supported
+        STD_AUTH_TYPES = %i[web jwt].freeze
+        private_constant :AOC_PATH_API_CLIENTS, :REDIRECT_LOCALHOST, :STD_AUTH_TYPES
         class << self
           def application_name
             'Aspera on Cloud'
@@ -30,13 +33,13 @@ module Aspera
             # no protocol ?
             base_url = "https://#{base_url}" unless base_url.match?(%r{^[a-z]{1,6}://})
             # only org provided ?
-            base_url = "#{base_url}.#{Aspera::AoC::PROD_DOMAIN}" unless base_url.include?('.')
+            base_url = "#{base_url}.#{Api::AoC::PROD_DOMAIN}" unless base_url.include?('.')
             # AoC is only https
             return nil unless base_url.start_with?('https://')
-            result = Rest.new({base_url: base_url, redirect_max: 10}).read('')
+            result = Rest.new(base_url: base_url, redirect_max: 10).read('')
             # Any AoC is on this domain
-            return nil unless result[:http].uri.host.end_with?(Aspera::AoC::PROD_DOMAIN)
-            Log.log.debug{'AoC Main page: #{result[:http].body.include?(Aspera::AoC::PRODUCT_NAME)}'}
+            return nil unless result[:http].uri.host.end_with?(Api::AoC::PROD_DOMAIN)
+            Log.log.debug{"AoC Main page: #{result[:http].body.include?(Api::AoC::PRODUCT_NAME)}"}
             base_url = result[:http].uri.to_s if result[:http].uri.path.include?('/public')
             # either in standard domain, or product name in page
             return {
@@ -47,7 +50,7 @@ module Aspera
 
           def private_key_required?(url)
             # pub link do not need private key
-            return AoC.link_info(url)[:token].nil?
+            return Api::AoC.link_info(url)[:token].nil?
           end
 
           # @param [Hash] env : options, formatter
@@ -60,9 +63,9 @@ module Aspera
             options.declare(:use_generic_client, 'Wizard: AoC: use global or org specific jwt client id', values: :bool, default: true)
             options.parse_options!
             instance_url = options.get_option(:url, mandatory: true)
-            pub_link_info = AoC.link_info(instance_url)
+            pub_link_info = Api::AoC.link_info(instance_url)
             if !pub_link_info[:token].nil?
-              pub_api = Rest.new({base_url: "https://#{URI.parse(pub_link_info[:url]).host}/api/v1"})
+              pub_api = Rest.new(base_url: "https://#{URI.parse(pub_link_info[:url]).host}/api/v1")
               pub_info = pub_api.read('env/url_token_check', {token: pub_link_info[:token]})[:data]
               preset_value = {
                 link: instance_url
@@ -99,7 +102,7 @@ module Aspera
                 formatter.display_status('Navigate to: 𓃑  → Admin → Integrations → API Clients')
                 formatter.display_status('Check or create in integration:')
                 formatter.display_status("- name: #{@info[:name]}")
-                formatter.display_status("- redirect uri: #{DEFAULT_REDIRECT}")
+                formatter.display_status("- redirect uri: #{REDIRECT_LOCALHOST}")
                 formatter.display_status('- origin: localhost')
                 formatter.display_status('Use the generated client id and secret in the following prompts.'.red)
               end
@@ -112,13 +115,14 @@ module Aspera
               formatter.display_status('We will use web authentication to bootstrap.')
               auto_set_pub_key = true
               auto_set_jwt = true
-              aoc_api.oauth.generic_parameters[:grant_method] = :web
-              aoc_api.oauth.generic_parameters[:scope] = AoC::SCOPE_FILES_ADMIN
-              aoc_api.oauth.specific_parameters[:redirect_uri] = DEFAULT_REDIRECT
+              raise 'TODO'
+              # aoc_api.oauth.grant_method = :web
+              # aoc_api.oauth.scope = Api::AoC::SCOPE_FILES_ADMIN
+              # aoc_api.oauth.specific_parameters[:redirect_uri] = REDIRECT_LOCALHOST
             end
             myself = object.aoc_api.read('self')[:data]
             if auto_set_pub_key
-              raise Cli::Error, 'Public key is already set in profile (use --override=yes)' unless myself['public_key'].empty? || option_override
+              Aspera.assert(myself['public_key'].empty?, exception_class: Cli::Error){'Public key is already set in profile (use --override=yes)'} unless option_override
               formatter.display_status('Updating profile with the public key.')
               aoc_api.update("users/#{myself['id']}", {'public_key' => pub_key_pem})
             end
@@ -165,21 +169,25 @@ module Aspera
           client_registration_token
           client_access_key
           kms_profile].freeze
-        PACKAGE_QUERY_DEFAULT = {'archived' => false, 'exclude_dropbox_packages' => true, 'has_content' => true, 'received' => true}.freeze
+        PACKAGE_RECEIVED_BASE_QUERY = {
+          'archived'    => false,
+          'has_content' => true,
+          'received'    => true,
+          'completed'   => true}.freeze
 
-        def initialize(env)
-          super(env)
+        def initialize(**env)
+          super
           @cache_workspace_info = nil
           @cache_home_node_file = nil
           @cache_api_aoc = nil
-          options.declare(:auth, 'OAuth type of authentication', values: Oauth::STD_AUTH_TYPES, default: :jwt)
+          options.declare(:auth, 'OAuth type of authentication', values: STD_AUTH_TYPES, default: :jwt)
           options.declare(:client_id, 'OAuth API client identifier')
           options.declare(:client_secret, 'OAuth API client secret')
-          options.declare(:scope, 'OAuth scope for AoC API calls', default: AoC::SCOPE_FILES_USER)
+          options.declare(:scope, 'OAuth scope for AoC API calls', default: Api::AoC::SCOPE_FILES_USER)
           options.declare(:redirect_uri, 'OAuth API client redirect URI')
           options.declare(:private_key, 'OAuth JWT RSA private key PEM value (prefix file path with @file:)')
           options.declare(:passphrase, 'RSA private key passphrase')
-          options.declare(:workspace, 'Name of workspace', types: [String, NilClass], default: Aspera::AoC::DEFAULT_WORKSPACE)
+          options.declare(:workspace, 'Name of workspace', types: [String, NilClass], default: Api::AoC::DEFAULT_WORKSPACE)
           options.declare(:new_user_option, 'New user creation option for unknown package recipients')
           options.declare(:validate_metadata, 'Validate shared inbox metadata', values: :bool, default: true)
           options.parse_options!
@@ -190,9 +198,9 @@ module Aspera
         OPTIONS_NEW = %i[url auth client_id client_secret scope redirect_uri private_key passphrase username password workspace].freeze
 
         def api_from_options(new_base_path)
-          create_values = {subpath: new_base_path, secret_finder: @agents[:config]}
+          create_values = {subpath: new_base_path, secret_finder: config}
           # create an API object with the same options, but with a different subpath
-          return Aspera::AoC.new(**OPTIONS_NEW.each_with_object(create_values) { |i, m|m[i] = options.get_option(i) unless options.get_option(i).nil?})
+          return Api::AoC.new(**OPTIONS_NEW.each_with_object(create_values) { |i, m|m[i] = options.get_option(i) unless options.get_option(i).nil?})
         rescue ArgumentError => e
           if (m = e.message.match(/missing keyword: :(.*)$/))
             raise Cli::Error, "Missing option: #{m[1]}"
@@ -201,7 +209,14 @@ module Aspera
         end
 
         def aoc_api
-          @cache_api_aoc = api_from_options(AoC::API_V1) if @cache_api_aoc.nil?
+          if @cache_api_aoc.nil?
+            @cache_api_aoc = api_from_options(Api::AoC::API_V1)
+            organization = @cache_api_aoc.read('organization')[:data]
+            if organization['http_gateway_enabled'] && organization['http_gateway_server_url']
+              transfer.httpgw_url_cb = lambda { organization['http_gateway_server_url'] }
+              # @cache_api_aoc.current_user_info['connect_disabled']
+            end
+          end
           return @cache_api_aoc
         end
 
@@ -209,7 +224,7 @@ module Aspera
         # @return identifier
         def get_resource_id_from_args(resource_class_path)
           return instance_identifier do |field, value|
-            raise Cli::BadArgument, 'only selection by name is supported' unless field.eql?('name')
+            Aspera.assert(field.eql?('name'), exception_class: Cli::BadArgument){'only selection by name is supported'}
             aoc_api.lookup_by_name(resource_class_path, value)['id']
           end
         end
@@ -218,11 +233,11 @@ module Aspera
           return "#{resource_class_path}/#{get_resource_id_from_args(resource_class_path)}"
         end
 
-        # Call aoc_api.read with same parameters.
-        # Use paging if necessary to get all results
-        # @return [Hash] {list: , total: }
-        def read_with_paging(resource_class_path, base_query)
-          raise 'Query must be Hash' unless base_query.is_a?(Hash)
+        # Call block with same query using paging and response information
+        # @return [Hash] {data: , total: }
+        def api_call_paging(base_query={})
+          Aspera.assert_type(base_query, Hash){'query'}
+          Aspera.assert(block_given?)
           # set default large page if user does not specify own parameters. AoC Caps to 1000 anyway
           base_query['per_page'] = 1000 unless base_query.key?('per_page')
           max_items = base_query.delete(MAX_ITEMS)
@@ -235,7 +250,7 @@ module Aspera
           loop do
             query = base_query.clone
             query['page'] = current_page
-            result = aoc_api.read(resource_class_path, query)
+            result = yield(query)
             total_count = result[:http]['X-Total-Count']
             page_count += 1
             current_page += 1
@@ -247,7 +262,38 @@ module Aspera
             break if !max_pages.nil? && page_count >= max_pages
           end
           item_list = item_list[0..max_items - 1] if !max_items.nil? && item_list.count > max_items
-          return {list: item_list, total: total_count}
+          return {data: item_list, total: total_count}
+        end
+
+        # read using the query and paging
+        # @return [Hash] {data: , total: }
+        def api_read_all(resource_class_path, base_query={})
+          return api_call_paging(base_query) do |query|
+            aoc_api.read(resource_class_path, query)
+          end
+        end
+
+        # list all entities, given additional, default and user's queries
+        def result_list(resource_class_path, fields: nil, base_query: {}, default_query: {})
+          Aspera.assert_type(base_query, Hash)
+          Aspera.assert_type(default_query, Hash)
+          user_query = query_read_delete(default: default_query)
+          # caller may add specific modifications or checks
+          yield(user_query) if block_given?
+          return {type: :object_list, fields: fields}.merge(api_read_all(resource_class_path, base_query.merge(user_query)))
+        end
+
+        def resolve_dropbox_name_default_ws_id(query)
+          if query.key?('dropbox_name')
+            # convenience: specify name instead of id
+            raise 'not both dropbox_name and dropbox_id' if query.key?('dropbox_id')
+            # TODO : craft a query that looks for dropbox only in current workspace
+            query['dropbox_id'] = aoc_api.lookup_by_name('dropboxes', query['dropbox_name'])['id']
+            query.delete('dropbox_name')
+          end
+          query['workspace_id'] ||= aoc_api.context[:workspace_id] unless aoc_api.context[:workspace_id].eql?(:undefined)
+          # by default show dropbox packages only for dropboxes
+          query['exclude_dropbox_packages'] = !query.key?('dropbox_id') unless query.key?('exclude_dropbox_packages')
         end
 
         NODE4_EXT_COMMANDS = %i[transfer].concat(Node::COMMANDS_GEN4).freeze
@@ -263,7 +309,7 @@ module Aspera
             scope:          scope
           )
           file_id = top_node_api.read("access_keys/#{top_node_api.app_info[:node_info]['access_key']}")[:data]['root_file_id'] if file_id.nil?
-          node_plugin = Node.new(@agents, api: top_node_api)
+          node_plugin = Node.new(**init_params, api: top_node_api)
           case command_repo
           when *Node::COMMANDS_GEN4
             return node_plugin.execute_command_gen4(command_repo, file_id)
@@ -275,20 +321,20 @@ module Aspera
             source_folder = options.get_next_argument('folder of source files', type: String)
             case push_pull
             when :push
-              client_direction = Fasp::TransferSpec::DIRECTION_SEND
+              client_direction = Transfer::Spec::DIRECTION_SEND
               client_folder = source_folder
               server_folder = transfer.destination_folder(client_direction)
             when :pull
-              client_direction = Fasp::TransferSpec::DIRECTION_RECEIVE
+              client_direction = Transfer::Spec::DIRECTION_RECEIVE
               client_folder = transfer.destination_folder(client_direction)
               server_folder = source_folder
-            else raise 'internal error'
+            else Aspera.error_unreachable_line
             end
             client_apfid = top_node_api.resolve_api_fid(file_id, client_folder)
             server_apfid = top_node_api.resolve_api_fid(file_id, server_folder)
             # force node as transfer agent
-            @agents[:transfer].agent_instance = Fasp::AgentNode.new({
-              url:      client_apfid[:api].params[:base_url],
+            transfer.agent_instance = Agent::Node.new({
+              url:      client_apfid[:api].base_url,
               username: client_apfid[:api].app_info[:node_info]['access_key'],
               password: client_apfid[:api].oauth_token,
               root_id:  client_apfid[:file_id]
@@ -303,22 +349,21 @@ module Aspera
               server_apfid[:file_id],
               client_direction,
               add_ts)))
-          else raise "INTERNAL ERROR: Missing case: #{command_repo}"
+          else Aspera.error_unreachable_line
           end # command_repo
-          # raise 'internal error:shall not reach here'
+          Aspera.error_unreachable_line
         end # execute_nodegen4_command
 
         def execute_admin_action
           # upgrade scope to admin
-          aoc_api.oauth.generic_parameters[:scope] = AoC::SCOPE_FILES_ADMIN
+          aoc_api.oauth.scope = Api::AoC::SCOPE_FILES_ADMIN
           command_admin = options.get_next_command(%i[ats resource usage_reports analytics subscription auth_providers])
           case command_admin
           when :auth_providers
             command_auth_prov = options.get_next_command(%i[list update])
             case command_auth_prov
             when :list
-              providers = aoc_api.read('admin/auth_providers')[:data]
-              return {type: :object_list, data: providers}
+              return result_list('admin/auth_providers')
             when :update
               raise 'not implemented'
             end
@@ -378,15 +423,15 @@ module Aspera
             result = bss_api.create('graphql', {'variables' => {'organization_id' => org['id']}, 'query' => graphql_query})[:data]['data']
             return {type: :single_object, data: result['aoc']['bssSubscription']}
           when :ats
-            ats_api = Rest.new(aoc_api.params.deep_merge({
-              base_url: "#{aoc_api.params[:base_url]}/admin/ats/pub/v1",
-              auth:     {scope: AoC::SCOPE_FILES_ADMIN_USER}
+            ats_api = Rest.new(**aoc_api.params.deep_merge({
+              base_url: "#{aoc_api.base_url}/admin/ats/pub/v1",
+              auth:     {scope: Api::AoC::SCOPE_FILES_ADMIN_USER}
             }))
-            return Ats.new(@agents).execute_action_gen(ats_api)
+            return Ats.new(**init_params).execute_action_gen(ats_api)
           when :analytics
-            analytics_api = Rest.new(aoc_api.params.deep_merge({
-              base_url: "#{aoc_api.params[:base_url].gsub('/api/v1', '')}/analytics/v2",
-              auth:     {scope: AoC::SCOPE_FILES_ADMIN_USER}
+            analytics_api = Rest.new(**aoc_api.params.deep_merge({
+              base_url: "#{aoc_api.base_url.gsub('/api/v1', '')}/analytics/v2",
+              auth:     {scope: Api::AoC::SCOPE_FILES_ADMIN_USER}
             }))
             command_analytics = options.get_next_command(%i[application_events transfers])
             case command_analytics
@@ -402,18 +447,22 @@ module Aspera
                 when :organizations then aoc_api.current_user_info['organization_id']
                 when :users then aoc_api.current_user_info['id']
                 when :nodes then aoc_api.current_user_info['id'] # TODO: consistent ? # rubocop:disable Lint/DuplicateBranch
-                else raise 'Internal error'
+                else Aspera.error_unreachable_line
                 end
               filter = options.get_option(:query) || {}
               filter['limit'] ||= 100
               if options.get_option(:once_only, mandatory: true)
                 saved_date = []
                 start_date_persistency = PersistencyActionOnce.new(
-                  manager: @agents[:persistency],
+                  manager: persistency,
                   data: saved_date,
-                  ids: IdGenerator.from_list(['aoc_ana_date', options.get_option(:url, mandatory: true), aoc_api.context[:workspace_name]].push(
+                  id: IdGenerator.from_list([
+                    'aoc_ana_date',
+                    options.get_option(:url, mandatory: true),
+                    aoc_api.context(:files)[:workspace_name],
                     filter_resource.to_s,
-                    filter_id)))
+                    filter_id
+                  ]))
                 start_date_time = saved_date.first
                 stop_date_time = Time.now.utc.strftime('%FT%T.%LZ')
                 # Log.log().error("start: #{start_date_time}")
@@ -484,9 +533,7 @@ module Aspera
               when :group_membership then default_fields.push(*%w[group_id member_type member_id])
               when :workspace_membership then default_fields.push(*%w[workspace_id member_type member_id])
               end
-              items = read_with_paging(resource_class_path, query_read_delete(default: default_query))
-              formatter.display_item_count(items[:list].length, items[:total])
-              return {type: :object_list, data: items[:list], fields: default_fields}
+              return result_list(resource_class_path, fields: default_fields, default_query: default_query)
             when :show
               object = aoc_api.read(resource_instance_path)[:data]
               # default: show all, but certificate
@@ -511,12 +558,13 @@ module Aspera
               return Main.result_success
             when :do
               command_repo = options.get_next_command(NODE4_EXT_COMMANDS)
-              aoc_api.context(:none)
+              # init context
+              aoc_api.context(:files)
               return execute_nodegen4_command(command_repo, res_id)
-            else raise 'unknown command'
+            else Aspera.error_unexpected_value(command)
             end
           when :usage_reports
-            return {type: :object_list, data: aoc_api.read('usage_reports', {workspace_id: aoc_api.context(:none)[:workspace_id]})[:data]}
+            return result_list('usage_reports', base_query: {workspace_id: aoc_api.context(:files)[:workspace_id]})
           end
         end
 
@@ -538,10 +586,10 @@ module Aspera
           when :reminder
             # send an email reminder with list of orgs
             user_email = options.get_option(:username, mandatory: true)
-            Rest.new(base_url: "#{AoC.api_base_url}/#{AoC::API_V1}").create('organization_reminders', {email: user_email})[:data]
+            Rest.new(base_url: "#{Api::AoC.api_base_url}/#{Api::AoC::API_V1}").create('organization_reminders', {email: user_email})[:data]
             return Main.result_status("List of organizations user is member of, has been sent by e-mail to #{user_email}")
           when :servers
-            return {type: :object_list, data: Rest.new(base_url: "#{AoC.api_base_url}/#{AoC::API_V1}").read('servers')[:data]}
+            return {type: :object_list, data: Rest.new(base_url: "#{Api::AoC.api_base_url}/#{Api::AoC::API_V1}").read('servers')[:data]}
           when :bearer_token
             return {type: :text, data: aoc_api.oauth_token}
           when :organization
@@ -549,15 +597,15 @@ module Aspera
           when :tier_restrictions
             return { type: :single_object, data: aoc_api.read('tier_restrictions')[:data] }
           when :user
-            case options.get_next_command(%i[workspaces profile])
+            case options.get_next_command(%i[workspaces profile preferences])
             # when :settings
             # return {type: :object_list,data: aoc_api.read('client_settings/')[:data]}
             when :workspaces
               case options.get_next_command(%i[list current])
               when :list
-                return {type: :object_list, data: aoc_api.read('workspaces')[:data], fields: %w[id name]}
+                return result_list('workspaces', fields: %w[id name])
               when :current
-                return { type: :single_object, data: aoc_api.read("workspaces/#{aoc_api.context(:none)[:workspace_id]}")[:data] }
+                return { type: :single_object, data: aoc_api.read("workspaces/#{aoc_api.context(:files)[:workspace_id]}")[:data] }
               end
             when :profile
               case options.get_next_command(%i[show modify])
@@ -567,19 +615,25 @@ module Aspera
                 aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", options.get_next_argument('properties', type: Hash))
                 return Main.result_status('modified')
               end
+            when :preferences
+              user_preferences_res = "users/#{aoc_api.current_user_info(exception: true)['id']}/user_interaction_preferences"
+              case options.get_next_command(%i[show modify])
+              when :show
+                return { type: :single_object, data: aoc_api.read(user_preferences_res)[:data] }
+              when :modify
+                aoc_api.update(user_preferences_res, options.get_next_argument('properties', type: Hash))
+                return Main.result_status('modified')
+              end
             end
           when :packages
-            package_command = options.get_next_command(%i[shared_inboxes send recv list show delete].concat(Node::NODE4_READ_ACTIONS))
+            package_command = options.get_next_command(%i[shared_inboxes send receive list show delete].concat(Node::NODE4_READ_ACTIONS), aliases: {recv: :receive})
             case package_command
             when :shared_inboxes
               case options.get_next_command(%i[list show])
               when :list
-                query = query_read_delete
-                if query.nil?
-                  query = {'embed[]' => 'dropbox', 'aggregate_permissions_by_dropbox' => true, 'sort' => 'dropbox_name'}
-                  query['workspace_id'] = aoc_api.context[:workspace_id] unless aoc_api.context[:workspace_id].eql?(:undefined)
-                end
-                return {type: :object_list, data: aoc_api.read('dropbox_memberships', query)[:data], fields: ['dropbox_id', 'dropbox.name']}
+                default_query = {'embed[]' => 'dropbox', 'aggregate_permissions_by_dropbox' => true, 'sort' => 'dropbox_name'}
+                default_query['workspace_id'] = aoc_api.context[:workspace_id] unless aoc_api.context[:workspace_id].eql?(:undefined)
+                return result_list('dropbox_memberships', fields: %w[dropbox_id dropbox.name], default_query: default_query)
               when :show
                 return {type: :single_object, data: aoc_api.read(get_resource_path_from_args('dropboxes'), query)[:data]}
               end
@@ -603,7 +657,7 @@ module Aspera
               Main.result_transfer(transfer.start(created_package[:spec], rest_token: created_package[:node]))
               # return all info on package (especially package id)
               return { type: :single_object, data: created_package[:info]}
-            when :recv
+            when :receive
               ids_to_download = nil
               if !aoc_api.public_link.nil?
                 aoc_api.assert_public_link_types(['view_received_package'])
@@ -615,8 +669,9 @@ module Aspera
               skip_ids_data = []
               skip_ids_persistency = nil
               if options.get_option(:once_only, mandatory: true)
+                # TODO: add query info to id
                 skip_ids_persistency = PersistencyActionOnce.new(
-                  manager: @agents[:persistency],
+                  manager: persistency,
                   data: skip_ids_data,
                   id: IdGenerator.from_list(
                     ['aoc_recv',
@@ -624,30 +679,30 @@ module Aspera
                      aoc_api.context[:workspace_id]
                     ].concat(aoc_api.additional_persistence_ids)))
               end
-              if ExtendedValue::ALL.eql?(ids_to_download)
-                query = query_read_delete(default: PACKAGE_QUERY_DEFAULT)
-                raise 'option query must be Hash' unless query.is_a?(Hash)
-                if query.key?('dropbox_name')
-                  # convenience: specify name instead of id
-                  raise 'not both dropbox_name and dropbox_id' if query.key?('dropbox_id')
-                  query['dropbox_id'] = aoc_api.lookup_by_name('dropboxes', query['dropbox_name'])['id']
-                  query.delete('dropbox_name')
-                end
-                query['workspace_id'] ||= aoc_api.context[:workspace_id] unless aoc_api.context[:workspace_id].eql?(:undefined)
-                # get list of packages in inbox
-                package_info = aoc_api.read('packages', query)[:data]
+              case ids_to_download
+              when ExtendedValue::ALL, ExtendedValue::INIT
+                query = query_read_delete(default: PACKAGE_RECEIVED_BASE_QUERY)
+                Aspera.assert_type(query, Hash){'query'}
+                resolve_dropbox_name_default_ws_id(query)
                 # remove from list the ones already downloaded
-                ids_to_download = package_info.map{|e|e['id']}
+                all_ids = api_read_all('packages', query)[:data].map{|e|e['id']}
+                if ids_to_download.eql?(ExtendedValue::INIT)
+                  Aspera.assert(skip_ids_persistency){'Only with option once_only'}
+                  skip_ids_persistency.data.clear.concat(all_ids)
+                  skip_ids_persistency.save
+                  return Main.result_status("Initialized skip for #{skip_ids_persistency.data.count} package(s)")
+                end
                 # array here
-                ids_to_download.reject!{|id|skip_ids_data.include?(id)}
+                ids_to_download = all_ids.reject{|id|skip_ids_data.include?(id)}
+              else
+                ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
               end # ExtendedValue::ALL
               # list here
-              ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
               result_transfer = []
               formatter.display_status("found #{ids_to_download.length} package(s).")
               ids_to_download.each do |package_id|
                 package_info = aoc_api.read("packages/#{package_id}")[:data]
-                formatter.display_status("downloading package: #{package_info['name']}")
+                formatter.display_status("downloading package: [#{package_info['id']}] #{package_info['name']}")
                 package_node_api = aoc_api.node_api_from(
                   node_id: package_info['node_id'],
                   workspace_id: aoc_api.context[:workspace_id],
@@ -656,7 +711,7 @@ module Aspera
                 statuses = transfer.start(
                   package_node_api.transfer_spec_gen4(
                     package_info['contents_file_id'],
-                    Fasp::TransferSpec::DIRECTION_RECEIVE,
+                    Transfer::Spec::DIRECTION_RECEIVE,
                     {'paths'=> [{'source' => '.'}]}),
                   rest_token: package_node_api)
                 result_transfer.push({'package' => package_id, Main::STATUS_FIELD => statuses})
@@ -673,36 +728,25 @@ module Aspera
               return { type: :single_object, data: package_info }
             when :list
               display_fields = %w[id name bytes_transferred]
-              query = query_read_delete(default: PACKAGE_QUERY_DEFAULT)
-              raise 'option query must be Hash' unless query.is_a?(Hash)
-              if query.key?('dropbox_name')
-                # convenience: specify name instead of id
-                raise 'not both dropbox_name and dropbox_id' if query.key?('dropbox_id')
-                query['dropbox_id'] = aoc_api.lookup_by_name('dropboxes', query['dropbox_name'])['id']
-                query.delete('dropbox_name')
-              end
-              if aoc_api.context[:workspace_id].eql?(:undefined)
-                display_fields.push('workspace_id')
-              else
-                query['workspace_id'] ||= aoc_api.context[:workspace_id]
-              end
-              packages = aoc_api.read('packages', query)[:data]
-              return {type: :object_list, data: packages, fields: display_fields}
+              display_fields.push('workspace_id') if aoc_api.context[:workspace_id].eql?(:undefined)
+              return result_list('packages', fields: display_fields, base_query: PACKAGE_RECEIVED_BASE_QUERY) do |query|
+                       resolve_dropbox_name_default_ws_id(query)
+                     end
             when :delete
               return do_bulk_operation(command: package_command, descr: 'identifier', values: identifier) do |id|
-                raise 'expecting String identifier' unless id.is_a?(String) || id.is_a?(Integer)
+                Aspera.assert_values(id.class, [String, Integer]){'identifier'}
                 aoc_api.delete("packages/#{id}")[:data]
               end
             when *Node::NODE4_READ_ACTIONS
               package_id = instance_identifier
               package_info = aoc_api.read("packages/#{package_id}")[:data]
-              return execute_nodegen4_command(package_command, package_info['node_id'], file_id: package_info['file_id'], scope: Aspera::Node::SCOPE_USER)
+              return execute_nodegen4_command(package_command, package_info['node_id'], file_id: package_info['file_id'], scope: Api::Node::SCOPE_USER)
             end
           when :files
             command_repo = options.get_next_command([:short_link].concat(NODE4_EXT_COMMANDS))
             case command_repo
             when *NODE4_EXT_COMMANDS
-              return execute_nodegen4_command(command_repo, aoc_api.context[:home_node_id], file_id: aoc_api.context[:home_file_id], scope: Aspera::Node::SCOPE_USER)
+              return execute_nodegen4_command(command_repo, aoc_api.context[:home_node_id], file_id: aoc_api.context[:home_file_id], scope: Api::Node::SCOPE_USER)
             when :short_link
               link_type = options.get_next_argument('link type', expected: %i[public private])
               short_link_command = options.get_next_command(%i[create delete list])
@@ -720,7 +764,7 @@ module Aspera
               purpose = case link_type
               when :public  then 'token_auth_redirection'
               when :private then 'shared_folder_auth_link'
-              else raise 'internal error'
+              else Aspera.error_unreachable_line
               end
               case short_link_command
               when :delete
@@ -754,8 +798,7 @@ module Aspera
                   # embed: 'updated_by_user',
                   sort:        '-created_at'
                 }
-                result = aoc_api.read('short_links', list_params)[:data]
-                return {type: :object_list, data: result, fields: Formatter.all_but('data')}
+                return result_list('short_links', fields: Formatter.all_but('data'), base_query: list_params)
               when :create
                 creation_params = {
                   purpose:            purpose,
@@ -781,7 +824,7 @@ module Aspera
                 if link_type.eql?(:public)
                   # TODO: merge with node permissions ?
                   # TODO: access level as arg
-                  access_levels = Aspera::Node::ACCESS_LEVELS # ['delete','list','mkdir','preview','read','rename','write']
+                  access_levels = Api::Node::ACCESS_LEVELS # ['delete','list','mkdir','preview','read','rename','write']
                   folder_name = File.basename(folder_dest)
                   perm_data = {
                     'file_id'       => shared_apfid[:file_id],
@@ -810,9 +853,7 @@ module Aspera
           when :automation
             Log.log.warn('BETA: work under progress')
             # automation api is not in the same place
-            automation_rest_params = aoc_api.params.clone
-            automation_rest_params[:base_url].gsub!('/api/', '/automation/')
-            automation_api = Rest.new(automation_rest_params)
+            automation_api = Rest.new(**aoc_api.params.merge(base_url: aoc_api.base_url.gsub('/api/', '/automation/')))
             command_automation = options.get_next_command(%i[workflows instances])
             case command_automation
             when :instances
@@ -846,21 +887,16 @@ module Aspera
             url = value_create_modify(command: command, type: String)
             uri = URI.parse(url)
             server = WebServerSimple.new(uri)
-            server.mount(uri.path, Faspex4GWServlet, aoc_api, aoc_api.context(:none)[:workspace_id])
-            trap('INT') { server.shutdown }
-            formatter.display_status("Faspex 4 gateway listening on #{url}")
-            Log.log.info("Listening on #{url}")
-            # this is blocking until server exits
+            server.mount(uri.path, Faspex4GWServlet, aoc_api, aoc_api.context(:files)[:workspace_id])
             server.start
             return Main.result_status('Gateway terminated')
-          else
-            raise "internal error: #{command}"
+          else Aspera.error_unreachable_line
           end # action
-          raise 'internal error: command shall return'
+          Aspera.error_unreachable_line
         end
 
         private :execute_admin_action
-      end # AoC
-    end # Plugins
-  end # Cli
-end # Aspera
+      end
+    end
+  end
+end