aspera-cli 4.21.2 → 4.23.0

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

@@ -50,10 +50,13 @@ module Aspera
           'archived'    => false,
           'has_content' => true,
           'received'    => true,
-          'completed'   => true}.freeze
+          'completed'   => true
+        }.freeze
+        PACKAGE_LIST_DEFAULT_FIELDS = %w[id name created_at files_completed bytes_transferred].freeze
         # options and parameters for Api::AoC.new
         OPTIONS_NEW = %i[url auth client_id client_secret scope redirect_uri private_key passphrase username password workspace].freeze
-        private_constant :REDIRECT_LOCALHOST, :STD_AUTH_TYPES, :ADMIN_OBJECTS, :PACKAGE_RECEIVED_BASE_QUERY, :OPTIONS_NEW
+
+        private_constant :REDIRECT_LOCALHOST, :STD_AUTH_TYPES, :ADMIN_OBJECTS, :PACKAGE_RECEIVED_BASE_QUERY, :OPTIONS_NEW, :PACKAGE_LIST_DEFAULT_FIELDS
         class << self
           def application_name
             'Aspera on Cloud'
@@ -78,15 +81,16 @@ module Aspera
             }
           end
 
-          # @param [String] url : url to check
+          # @param url [String] url to check
           # @return [Bool] true if private key is required for the url (i.e. no passcode)
           def private_key_required?(url)
             # pub link do not need private key
             return Api::AoC.link_info(url)[:token].nil?
           end
 
-          # @param [Hash] env : options, formatter
-          # @param [Hash] params : plugin_sym, instance_url
+          # @param object [Plugin] An instance of this class
+          # @param private_key_path [String] path to private key
+          # @param pub_key_pem [String] PEM of public key
           # @return [Hash] :preset_value, :test_args
           def wizard(object:, private_key_path: nil, pub_key_pem: nil)
             # set vars to look like object
@@ -121,7 +125,7 @@ module Aspera
               formatter.display_status('Please Login to your Aspera on Cloud instance.')
               formatter.display_status('Navigate to: 👤 → Account Settings → Profile → Public Key')
               formatter.display_status('Check or update the value to:'.red.blink)
-              formatter.display_status(pub_key_pem)
+              formatter.display_status(pub_key_pem, hide_secrets: false)
               if !options.get_option(:test_mode)
                 formatter.display_status('Once updated or validated, press enter.')
                 Environment.instance.open_uri(instance_url)
@@ -188,22 +192,28 @@ module Aspera
           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: Api::AoC::SCOPE_FILES_USER)
+          options.declare(:scope, 'OAuth scope for AoC API calls')
           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', types: String)
           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', types: Hash)
           options.declare(:validate_metadata, 'Validate shared inbox metadata', values: :bool, default: true)
+          options.declare(:package_folder, 'Field of package to use as folder name, or @none:', types: [String, NilClass])
           options.parse_options!
           # add node plugin options (for manual)
           Node.declare_options(options)
         end
 
-        def api_from_options(new_base_path)
-          create_values = {subpath: new_base_path, secret_finder: config}
+        def api_from_options(aoc_base_path)
+          create_values = OPTIONS_NEW.each_with_object({
+            subpath:       aoc_base_path,
+            secret_finder: config}) do |i, m|
+            m[i] = options.get_option(i) unless options.get_option(i).nil?
+          end
+          create_values[:scope] = Api::AoC::SCOPE_FILES_USER if create_values[:scope].nil?
           # create an API object with the same options, but with a different subpath
-          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?})
+          return Api::AoC.new(**create_values)
         rescue ArgumentError => e
           if (m = e.message.match(/missing keyword: :(.*)$/))
             raise Cli::Error, "Missing option: #{m[1]}"
@@ -216,13 +226,31 @@ module Aspera
             @cache_api_aoc = api_from_options(Api::AoC::API_V1)
             organization = @cache_api_aoc.read('organization')
             if organization['http_gateway_enabled'] && organization['http_gateway_server_url']
-              transfer.httpgw_url_cb = lambda { 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
 
+        # Generate or update Hash with workspace id and name (option), if not already set
+        # @param hash   [Hash, Nil] set in provided hash
+        # @param string [Bool] true to set key as string, else as symbol
+        # @param name   [Bool] include name
+        # @return [Hash] with key `workspace_[id,name]` (symbol or string) only if defined
+        def workspace_id_hash(hash: nil, string: false, name: false)
+          info = aoc_api.workspace
+          hash = {} if hash.nil?
+          fields = %i[id]
+          fields.push(:name) if name
+          fields.each do |i|
+            k = "workspace_#{i}"
+            k = k.to_sym unless string
+            hash[k] = info[i] unless info[i].nil? || hash.key?(k)
+          end
+          return hash
+        end
+
         # Get resource identifier from command line, either directly or from name.
         # @param resource_class_path url path for resource
         # @return identifier
@@ -240,7 +268,7 @@ module Aspera
 
         # Call block with same query using paging and response information
         # block must return a hash with :data and :http keys
-        # @return [Hash] {data: , total: }
+        # @return [Hash] {items: , total: }
         def api_call_paging(base_query={})
           Aspera.assert_type(base_query, Hash){'query'}
           Aspera.assert(block_given?)
@@ -268,46 +296,59 @@ module Aspera
             item_list += add_items
             break if !max_items.nil? && item_list.count >= max_items
             break if !max_pages.nil? && page_count >= max_pages
+            formatter.long_operation_running("#{item_list.count} / #{total_count}") unless total_count.eql?(item_list.count.to_s)
           end
+          formatter.long_operation_terminated
           item_list = item_list[0..max_items - 1] if !max_items.nil? && item_list.count > max_items
-          return {data: item_list, total: total_count}
+          return {items: 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.call(operation: 'GET', subpath: resource_class_path, headers: {'Accept' => 'application/json'}, query: query)
+            aoc_api.call(operation: 'GET', subpath: resource_class_path, headers: {'Accept' => Rest::MIME_JSON}, query: query)
           end
         end
 
-        # list all entities, given additional, default and user's queries
+        # List all entities, given additional, default and user's queries
         # @param resource_class_path path to query on API
         # @param fields fields to display
         # @param base_query a query applied always
         # @param default_query default query unless overriden by user
+        # @param &block (Optional) calls block with user's or default query
         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).compact))
+          query = query_read_delete(default: default_query)
+          # caller may add specific modifications or checks to query
+          yield(query) if block_given?
+          result = api_read_all(resource_class_path, base_query.merge(query).compact)
+          return Main.result_object_list(result[:items], fields: fields, total: result[:total])
         end
 
+        # Translates `dropbox_name` to `dropbox_id` and fills current workspace_id
         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')
+            raise 'Use field dropbox_name or dropbox_id, not both' 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')
+            query['dropbox_id'] = aoc_api.lookup_by_name('dropboxes', query.delete('dropbox_name'))['id']
           end
-          query['workspace_id'] ||= aoc_api.workspace[:id] unless aoc_api.workspace[:id].eql?(:undefined)
+          workspace_id_hash(hash: query, string: true)
           # by default show dropbox packages only for dropboxes
           query['exclude_dropbox_packages'] = !query.key?('dropbox_id') unless query.key?('exclude_dropbox_packages')
         end
 
+        # @return [Hash] {items,total} with all packages according to combination of user's query and default query
+        def list_all_packages_with_query
+          query = query_read_delete(default: {})
+          Aspera.assert_type(query, Hash){'query'}
+          PACKAGE_RECEIVED_BASE_QUERY.each{ |k, v| query[k] = v unless query.key?(k)}
+          resolve_dropbox_name_default_ws_id(query)
+          return api_read_all('packages', query.compact)
+        end
+
         NODE4_EXT_COMMANDS = %i[transfer].concat(Node::COMMANDS_GEN4).freeze
         private_constant :NODE4_EXT_COMMANDS
 
@@ -316,9 +357,8 @@ module Aspera
         def execute_nodegen4_command(command_repo, node_id, file_id: nil, scope: nil)
           top_node_api = aoc_api.node_api_from(
             node_id:        node_id,
-            workspace_id:   aoc_api.workspace[:id],
-            workspace_name: aoc_api.workspace[:name],
-            scope:          scope
+            scope:          scope,
+            **workspace_id_hash(name: true)
           )
           file_id = top_node_api.read("access_keys/#{top_node_api.app_info[:node_info]['access_key']}")['root_file_id'] if file_id.nil?
           node_plugin = Node.new(**init_params, api: top_node_api)
@@ -410,7 +450,9 @@ module Aspera
               default_fields.push('app_type', 'app_name', 'available', 'direct_authorizations_allowed', 'workspace_authorizations_allowed')
             when :client, :client_access_key, :dropbox, :group, :package, :saml_configuration, :workspace then default_fields.push('name')
             when :client_registration_token then default_fields.push('value', 'data.client_subject_scopes', 'created_at')
-            when :contact then default_fields = %w[email name source_id source_type]
+            when :contact
+              default_fields = %w[source_type source_id name email]
+              default_query = {'include_only_user_personal_contacts' => true} if aoc_api.oauth.scope == Api::AoC::SCOPE_FILES_USER
             when :node then default_fields.push('name', 'host', 'access_key')
             when :operation then default_fields = nil
             when :short_link then default_fields.push('short_url', 'data.url_token_data.purpose')
@@ -422,8 +464,8 @@ module Aspera
           when :show
             object = aoc_api.read(resource_instance_path)
             # default: show all, but certificate
-            fields = object.keys.reject{|k|k.eql?('certificate')}
-            return { type: :single_object, data: object, fields: fields }
+            fields = object.keys.reject{ |k| k.eql?('certificate')}
+            return Main.result_single_object(object, fields: fields)
           when :modify
             changes = options.get_next_argument('properties', validation: Hash)
             return do_bulk_operation(command: command, descr: 'identifier', values: res_id) do |one_id|
@@ -453,8 +495,8 @@ module Aspera
         ADMIN_ACTIONS = %i[ats resource usage_reports analytics subscription auth_providers].concat(ADMIN_OBJECTS).freeze
 
         def execute_admin_action
-          # upgrade scope to admin
-          aoc_api.oauth.scope = Api::AoC::SCOPE_FILES_ADMIN
+          # default scope to admin
+          aoc_api.oauth.scope = Api::AoC::SCOPE_FILES_ADMIN if options.get_option(:scope).nil?
           command_admin = options.get_next_command(ADMIN_ACTIONS)
           case command_admin
           when :resource
@@ -529,7 +571,7 @@ module Aspera
               GRAPHQL
               # cspell:enable
               result = bss_graphql.create(nil, {query: graphql_query, variables: {organization_id: org['id']}})['data']
-              return {type: :single_object, data: result['aoc']['bssSubscription']}
+              return Main.result_single_object(result['aoc']['bssSubscription'])
             when :usage
               # cspell:disable
               graphql_query = <<-GRAPHQL
@@ -576,7 +618,7 @@ module Aspera
                    aggregate:       aggregate,
                    startDate:       start_date,
                    endDate:         end_date}})['data']
-              return {type: :single_object, data: result['aoc']}
+              return Main.result_single_object(result['aoc'])
             end
           when :ats
             ats_api = Rest.new(**aoc_api.params.deep_merge({
@@ -594,7 +636,7 @@ module Aspera
             when :application_events
               event_type = command_analytics.to_s
               events = analytics_api.read("organizations/#{aoc_api.current_user_info['organization_id']}/#{event_type}")[event_type]
-              return {type: :object_list, data: events}
+              return Main.result_object_list(events)
             when :transfers
               event_type = command_analytics.to_s
               filter_resource = options.get_next_argument('resource', accept_list: %i[organizations users nodes])
@@ -635,25 +677,26 @@ module Aspera
                   config.send_email_template(values: {ev: tr_event})
                 end
               end
-              return {type: :object_list, data: events}
+              return Main.result_object_list(events)
             end
           when :usage_reports
             aoc_api.context = :files
-            return result_list('usage_reports', base_query: {workspace_id: aoc_api.workspace[:id]})
+            return result_list('usage_reports', base_query: workspace_id_hash)
           end
         end
 
         # Create a shared link for the given entity
-        # @param shared_data [Hash] information for shared data
-        # @param block [Proc] Optional: called on creation
-        def short_link_command(shared_data, purpose_public:)
+        # @param purpose_public [Symbol]
+        # @param shared_data    [Hash] information for shared data
+        # @param block          [Proc] Optional: called on creation
+        def short_link_command(purpose_public:, **shared_data)
           link_type = options.get_next_argument('link type', accept_list: %i[public private])
           purpose_local = case link_type
           when :public
             case purpose_public
             when /package/ then 'send_package_to_dropbox'
             when /shared/ then 'token_auth_redirection'
-            else raise 'error'
+            else Aspera.error_unexpected_value(purpose_public){'public link purpose'}
             end
           when :private then 'shared_folder_auth_link'
           else Aspera.error_unreachable_line
@@ -682,7 +725,7 @@ module Aspera
             result_create_short_link = aoc_api.create('short_links', creation_params)
             # public: Creation: permission on node
             yield(result_create_short_link['resource_id']) if block_given? && link_type.eql?(:public)
-            return {type: :single_object, data: result_create_short_link}
+            return Main.result_single_object(result_create_short_link)
           when :list
             query = if link_type.eql?(:private)
               shared_data
@@ -718,6 +761,26 @@ module Aspera
           end
         end
 
+        # @return persistency object if option `once_only` is used.
+        def package_persistency
+          return nil unless options.get_option(:once_only, mandatory: true)
+          # TODO: add query info to id
+          PersistencyActionOnce.new(
+            manager: persistency,
+            data: [],
+            id: IdGenerator.from_list(
+              ['aoc_recv',
+               options.get_option(:url, mandatory: true),
+               aoc_api.workspace[:id]
+              ].concat(aoc_api.additional_persistence_ids)))
+        end
+
+        def reject_packages_from_persistency(all_packages, skip_ids_persistency)
+          return if skip_ids_persistency.nil?
+          skip_package = skip_ids_persistency.data.each_with_object({}){ |i, m| m[i] = true}
+          all_packages.reject!{ |pkg| skip_package[pkg['id']]}
+        end
+
         # must be public
         ACTIONS = %i[reminder servers bearer_token organization tier_restrictions user packages files admin automation gateway].freeze
 
@@ -739,29 +802,31 @@ module Aspera
             Rest.new(base_url: "#{Api::AoC.api_base_url}/#{Api::AoC::API_V1}").create('organization_reminders', {email: user_email})
             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: "#{Api::AoC.api_base_url}/#{Api::AoC::API_V1}").read('servers')}
+            return Main.result_object_list(Rest.new(base_url: "#{Api::AoC.api_base_url}/#{Api::AoC::API_V1}").read('servers'))
           when :bearer_token
-            return {type: :text, data: aoc_api.oauth.authorization}
+            return Main.result_text(aoc_api.oauth.authorization)
           when :organization
-            return { type: :single_object, data: aoc_api.read('organization') }
+            return Main.result_single_object(aoc_api.read('organization'))
           when :tier_restrictions
-            return { type: :single_object, data: aoc_api.read('tier_restrictions') }
+            return Main.result_single_object(aoc_api.read('tier_restrictions'))
           when :user
-            case options.get_next_command(%i[workspaces profile preferences])
+            case options.get_next_command(%i[workspaces profile preferences contacts])
+            when :contacts
+              return execute_resource_action(:contact)
             # when :settings
-            # return {type: :object_list,data: aoc_api.read('client_settings/')}
+            # return Main.result_object_list(aoc_api.read('client_settings/'))
             when :workspaces
               case options.get_next_command(%i[list current])
               when :list
                 return result_list('workspaces', fields: %w[id name])
               when :current
                 aoc_api.context = :files
-                return { type: :single_object, data: aoc_api.read("workspaces/#{aoc_api.workspace[:id]}") }
+                return Main.result_single_object(aoc_api.workspace)
               end
             when :profile
               case options.get_next_command(%i[show modify])
               when :show
-                return { type: :single_object, data: aoc_api.current_user_info(exception: true) }
+                return Main.result_single_object(aoc_api.current_user_info(exception: true))
               when :modify
                 aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", options.get_next_argument('properties', validation: Hash))
                 return Main.result_status('modified')
@@ -770,7 +835,7 @@ module Aspera
               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) }
+                return Main.result_single_object(aoc_api.read(user_preferences_res))
               when :modify
                 aoc_api.update(user_preferences_res, options.get_next_argument('properties', validation: Hash))
                 return Main.result_status('modified')
@@ -783,26 +848,24 @@ module Aspera
               case options.get_next_command(%i[list show short_link])
               when :list
                 default_query = {'embed[]' => 'dropbox', 'aggregate_permissions_by_dropbox' => true, 'sort' => 'dropbox_name'}
-                default_query['workspace_id'] = aoc_api.workspace[:id] unless aoc_api.workspace[:id].eql?(:undefined)
+                workspace_id_hash(hash: default_query, string: true)
                 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'))}
+                return Main.result_single_object(aoc_api.read(get_resource_path_from_args('dropboxes')))
               when :short_link
                 return short_link_command(
-                  {
-                    workspace_id: aoc_api.workspace[:id],
-                    dropbox_id:   get_resource_id_from_args('dropboxes'),
-                    name:         ''
-                  },
-                  purpose_public: 'send_package_to_dropbox')
+                  purpose_public: 'send_package_to_dropbox',
+                  dropbox_id:     get_resource_id_from_args('dropboxes'),
+                  name:           '',
+                  **workspace_id_hash
+                )
               end
             when :send
               package_data = value_create_modify(command: package_command)
               new_user_option = options.get_option(:new_user_option)
               option_validate = options.get_option(:validate_metadata)
-              # works for both normal usr auth and link auth
-              package_data['workspace_id'] ||= aoc_api.workspace[:id]
-
+              # works for both normal user auth and link auth
+              workspace_id_hash(hash: package_data, string: true) unless package_data.key?('workspace_id')
               if !aoc_api.public_link.nil?
                 aoc_api.assert_public_link_types(%w[send_package_to_user send_package_to_dropbox])
                 box_type = aoc_api.public_link['purpose'].split('_').last
@@ -815,88 +878,73 @@ module Aspera
               created_package = aoc_api.create_package_simple(package_data, option_validate, new_user_option)
               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]}
+              return Main.result_single_object(created_package[:info])
             when :receive
               ids_to_download = nil
               if !aoc_api.public_link.nil?
                 aoc_api.assert_public_link_types(['view_received_package'])
-                # set the package id, it will
+                # set the package id from link
                 ids_to_download = aoc_api.public_link['data']['package_id']
               end
               # get from command line unless it was a public link
               ids_to_download ||= instance_identifier
-              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: persistency,
-                  data: skip_ids_data,
-                  id: IdGenerator.from_list(
-                    ['aoc_recv',
-                     options.get_option(:url, mandatory: true),
-                     aoc_api.workspace[:id]
-                    ].concat(aoc_api.additional_persistence_ids)))
-              end
+              skip_ids_persistency = package_persistency
               case ids_to_download
               when SpecialValues::ALL, SpecialValues::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
-                all_ids = api_read_all('packages', query)[:data].map{|e|e['id']}
+                all_packages = list_all_packages_with_query[:items]
                 if ids_to_download.eql?(SpecialValues::INIT)
-                  Aspera.assert(skip_ids_persistency){'Only with option once_only'}
-                  skip_ids_persistency.data.clear.concat(all_ids)
+                  Aspera.assert(skip_ids_persistency){'INIT requires option once_only'}
+                  skip_ids_persistency.data.clear.concat(all_packages.map{ |e| e['id']})
                   skip_ids_persistency.save
                   return Main.result_status("Initialized skip for #{skip_ids_persistency.data.count} package(s)")
                 end
-                # array here
-                ids_to_download = all_ids.reject{|id|skip_ids_data.include?(id)}
+                # remove from list the ones already downloaded
+                reject_packages_from_persistency(all_packages, skip_ids_persistency)
+                ids_to_download = all_packages.map{ |e| e['id']}
+                formatter.display_status("Found #{ids_to_download.length} package(s).")
               else
+                # single id to array
                 ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
               end
-              file_list =
-                begin
-                  transfer.source_list.map{|i|{'source'=>i}}
-                rescue Cli::BadArgument
-                  [{'source' => '.'}]
-                end
-              # list here
+              # download all files, or specified list only
+              ts_paths = transfer.ts_source_paths(default: ['.'])
+              per_package_field = options.get_option(:package_folder)
+              destination_folder = transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE)
               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}")
-                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.workspace[:id],
-                  workspace_name: aoc_api.workspace[:name],
-                  package_info: package_info)
+                  package_info: package_info,
+                  **workspace_id_hash(name: true))
+                transfer_spec = package_node_api.transfer_spec_gen4(
+                  package_info['contents_file_id'],
+                  Transfer::Spec::DIRECTION_RECEIVE,
+                  {'paths'=> ts_paths})
+                transfer.option_transfer_spec['destination_root'] = File.join(destination_folder, package_info[per_package_field]) unless per_package_field.nil?
+                formatter.display_status(%Q{Downloading package: [#{package_info['id']}] "#{package_info['name']}" to [#{transfer.option_transfer_spec['destination_root']}]})
                 statuses = transfer.start(
-                  package_node_api.transfer_spec_gen4(
-                    package_info['contents_file_id'],
-                    Transfer::Spec::DIRECTION_RECEIVE,
-                    {'paths'=> file_list}),
+                  transfer_spec,
                   rest_token: package_node_api)
                 result_transfer.push({'package' => package_id, Main::STATUS_FIELD => statuses})
                 # update skip list only if all transfer sessions completed
-                if TransferAgent.session_status(statuses).eql?(:success)
-                  skip_ids_data.push(package_id)
-                  skip_ids_persistency&.save
+                if skip_ids_persistency && TransferAgent.session_status(statuses).eql?(:success)
+                  skip_ids_persistency.data.push(package_id)
+                  skip_ids_persistency.save
                 end
               end
               return Main.result_transfer_multiple(result_transfer)
             when :show
               package_id = instance_identifier
               package_info = aoc_api.read("packages/#{package_id}")
-              return { type: :single_object, data: package_info }
+              return Main.result_single_object(package_info)
             when :list
-              display_fields = %w[id name bytes_transferred]
-              display_fields.push('workspace_id') if aoc_api.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
+              result = list_all_packages_with_query
+              skip_ids_persistency = package_persistency
+              reject_packages_from_persistency(result[:items], skip_ids_persistency)
+              display_fields = PACKAGE_LIST_DEFAULT_FIELDS
+              display_fields += ['workspace_id'] if aoc_api.workspace[:id].nil?
+              return Main.result_object_list(result[:items], fields: display_fields, total: result[:total])
             when :delete
               return do_bulk_operation(command: package_command, descr: 'identifier', values: instance_identifier) do |id|
                 Aspera.assert_values(id.class, [String, Integer]){'identifier'}
@@ -915,16 +963,15 @@ module Aspera
             when :short_link
               folder_dest = options.get_next_argument('path', validation: String)
               home_node_api = aoc_api.node_api_from(
-                node_id:        aoc_api.home[:node_id],
-                workspace_id:   aoc_api.workspace[:id],
-                workspace_name: aoc_api.workspace[:name])
+                node_id: aoc_api.home[:node_id],
+                **workspace_id_hash(name: true))
               shared_apfid = home_node_api.resolve_api_fid(aoc_api.home[:file_id], folder_dest)
               return short_link_command(
-                {
-                  workspace_id: aoc_api.workspace[:id],
-                  node_id:      shared_apfid[:api].app_info[:node_info]['id'],
-                  file_id:      shared_apfid[:file_id]
-                }, purpose_public: 'view_shared_file') do |resource_id|
+                purpose_public: 'view_shared_file',
+                node_id:        shared_apfid[:api].app_info[:node_info]['id'],
+                file_id:        shared_apfid[:file_id],
+                **workspace_id_hash
+              ) do |resource_id|
                        # TODO: merge with node permissions ?
                        # TODO: access level as arg
                        access_levels = Api::Node::ACCESS_LEVELS # ['delete','list','mkdir','preview','read','rename','write']
@@ -936,13 +983,12 @@ module Aspera
                          'tags'          => {
                            # TODO: really just here ? not in tags.aspera.files.workspace ?
                            'url_token'        => true,
-                           'workspace_id'     => aoc_api.workspace[:id],
-                           'workspace_name'   => aoc_api.workspace[:name],
                            'folder_name'      => File.basename(folder_dest),
                            'created_by_name'  => aoc_api.current_user_info['name'],
                            'created_by_email' => aoc_api.current_user_info['email'],
                            'access_key'       => shared_apfid[:api].app_info[:node_info]['access_key'],
-                           'node'             => shared_apfid[:api].app_info[:node_info]['host']
+                           'node'             => shared_apfid[:api].app_info[:node_info]['host'],
+                           **workspace_id_hash(string: true, name: true)
                          }
                        }
                        created_data = shared_apfid[:api].create('permissions', perm_data)
@@ -965,7 +1011,7 @@ module Aspera
               when :launch
                 wf_id = instance_identifier
                 data = automation_api.create("workflows/#{wf_id}/launch", {})
-                return {type: :single_object, data: data}
+                return Main.result_single_object(data)
               when :action
                 # TODO: not complete
                 wf_id = instance_identifier
@@ -976,16 +1022,17 @@ module Aspera
                 action = automation_api.create('actions', {'step_id' => step['id'], 'type' => 'manual'})
                 automation_api.update("steps/#{step['id']}", {'action_order' => [action['id']]})
                 wf = automation_api.read("workflows/#{wf_id}")
-                return {type: :single_object, data: wf}
+                return Main.result_single_object(wf)
               end
             end
           when :admin
             return execute_admin_action
           when :gateway
             require 'aspera/faspex_gw'
-            url = value_create_modify(command: command, type: String)
-            uri = URI.parse(url)
-            server = WebServerSimple.new(uri)
+            parameters = value_create_modify(command: command, default: {}).symbolize_keys
+            uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
+            server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
+            Aspera.assert(parameters.except(*WebServerSimple::PARAMS).empty?)
             aoc_api.context = :files
             server.mount(uri.path, Faspex4GWServlet, aoc_api, aoc_api.workspace[:id])
             server.start