aspera-cli 4.21.1 → 4.22.0

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

@@ -53,7 +53,9 @@ module Aspera
           'completed'   => true}.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
+        PACKAGE_LIST_DEFAULT_FIELDS = %w[id name created_at files_completed bytes_transferred].freeze
+
+        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 +80,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 +124,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)
@@ -203,7 +206,7 @@ module Aspera
         def api_from_options(new_base_path)
           create_values = {subpath: new_base_path, secret_finder: config}
           # 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(**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]}"
@@ -216,13 +219,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 +261,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 +289,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 +350,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)
@@ -348,7 +381,7 @@ module Aspera
             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,
+              password: client_apfid[:api].oauth.authorization,
               root_id:  client_apfid[:file_id]
             )
             # additional node to node TS info
@@ -422,8 +455,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|
@@ -473,60 +506,111 @@ module Aspera
           when :subscription
             org = aoc_api.read('organization')
             bss_graphql = api_from_options('bss/platform/graphql')
-            # cspell:disable
-            graphql_query = <<-GRAPHQL
-      query ($organization_id: ID!) {
-        aoc (organization_id: $organization_id) {
-          bssSubscription {
-            aocVersion
-            endDate
-            startDate
-            termMonths
-            plan
-            trial
-            termType
-            aocOrganizations {
-              id
-            }
-            additionalStorageVolumeGb
-            additionalEgressVolumeGb
-            term {
-              startDate
-              endDate
-              transferVolumeGb
-              egressVolumeGb
-              storageVolumeGb
-              transferVolumeOffsetGb
-            }
-            paygoRate {
-              transferRate
-              storageRate
-              currency
-            }
-            aocPlanData {
-              tier
-              trial
-              workspaces { max }
-              users {
-                planAmount
-                max
+            command_subscription = options.get_next_command(%i[account usage])
+            case command_subscription
+            when :account
+              # cspell:disable
+              graphql_query = <<-GRAPHQL
+              query ($organization_id: ID!) {
+                aoc (organization_id: $organization_id) {
+                  bssSubscription {
+                    aocVersion
+                    endDate
+                    startDate
+                    termMonths
+                    plan
+                    trial
+                    termType
+                    aocOrganizations {
+                      id
+                    }
+                    additionalStorageVolumeGb
+                    additionalEgressVolumeGb
+                    term {
+                      startDate
+                      endDate
+                      transferVolumeGb
+                      egressVolumeGb
+                      storageVolumeGb
+                      transferVolumeOffsetGb
+                    }
+                    paygoRate {
+                      transferRate
+                      storageRate
+                      currency
+                    }
+                    aocPlanData {
+                      tier
+                      trial
+                      workspaces { max }
+                      users {
+                        planAmount
+                        max
+                      }
+                      samlIntegration
+                      activity
+                      sharedInboxes
+                      uniqueUrls
+                      support
+                      watermarking
+                      byok
+                      automation { planAmount, max }
+                    }
+                  }
+                }
               }
-              samlIntegration
-              activity
-              sharedInboxes
-              uniqueUrls
-              support
-              watermarking
-              byok
-              automation { planAmount, max }
-            }
-          }
-        }
-      }
-            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']}
+              GRAPHQL
+              # cspell:enable
+              result = bss_graphql.create(nil, {query: graphql_query, variables: {organization_id: org['id']}})['data']
+              return Main.result_single_object(result['aoc']['bssSubscription'])
+            when :usage
+              # cspell:disable
+              graphql_query = <<-GRAPHQL
+              query ($organization_id: ID!, $startDate: Date!, $endDate: Date!, $aggregate: TransferUsageAggregateOption!) {
+                aoc (organization_id: $organization_id) {
+                  bssSubscription {
+                    aocOrganizations { id }
+                    additionalStorageVolumeGb
+                    additionalEgressVolumeGb
+                    aocPlanData {
+                      tier
+                      trial
+                    }
+                    term {
+                      transferVolumeGb
+                      egressVolumeGb
+                      storageVolumeGb
+                      startDate
+                      endDate
+                      transferVolumeOffsetGb
+                    }
+                    termMonths
+                    transferUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { mbTotal }
+                    egressUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { usageMb }
+                  }
+                  subscriptionEntitlements {
+                    id
+                    transferUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { mbTotal }
+                    egressUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { usageMb }
+                  }
+                }
+              }
+              GRAPHQL
+              aggregate = options.get_next_argument('aggregation', accept_list: %i[ALL MONTHLY], default: :ALL)
+              today = Date.today
+              start_date = options.get_next_argument('start date', mandatory: false, default: today.prev_year.strftime('%Y-%m-%d'))
+              end_date = options.get_next_argument('end date', mandatory: false, default: today.strftime('%Y-%m-%d'))
+              # cspell:enable
+              result = bss_graphql.create(
+                nil,
+                {query:     graphql_query,
+                 variables: {
+                   organization_id: org['id'],
+                   aggregate:       aggregate,
+                   startDate:       start_date,
+                   endDate:         end_date}})['data']
+              return Main.result_single_object(result['aoc'])
+            end
           when :ats
             ats_api = Rest.new(**aoc_api.params.deep_merge({
               base_url: "#{aoc_api.base_url}/admin/ats/pub/v1",
@@ -543,7 +627,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])
@@ -584,25 +668,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
@@ -631,7 +716,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
@@ -667,6 +752,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
 
@@ -688,29 +793,29 @@ 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.token}
+            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])
             # 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')
@@ -719,7 +824,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')
@@ -732,26 +837,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
@@ -764,64 +867,49 @@ 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']}
               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}}
+                  transfer.source_list.map{ |i| {'source'=>i}}
                 rescue Cli::BadArgument
                   [{'source' => '.'}]
                 end
               # list here
               result_transfer = []
-              formatter.display_status("found #{ids_to_download.length} package(s).")
+              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))
                 statuses = transfer.start(
                   package_node_api.transfer_spec_gen4(
                     package_info['contents_file_id'],
@@ -830,22 +918,23 @@ module Aspera
                   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'}
@@ -864,16 +953,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']
@@ -885,13 +973,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)
@@ -914,7 +1001,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
@@ -925,16 +1012,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