aspera-cli 4.22.0 → 4.24.0

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

@@ -44,16 +44,18 @@ module Aspera
           application
           client_registration_token
           client_access_key
-          kms_profile].freeze
+          kms_profile
+        ].freeze
         # query to list fully received packages
         PACKAGE_RECEIVED_BASE_QUERY = {
           '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
-        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
@@ -67,12 +69,12 @@ module Aspera
             # only org provided ?
             base_url = "#{base_url}.#{Api::AoC::SAAS_DOMAIN_PROD}" unless base_url.include?('.')
             # AoC is only https
-            return nil unless base_url.start_with?('https://')
+            return unless base_url.start_with?('https://')
             res_http = Rest.new(base_url: base_url, redirect_max: 0).call(operation: 'GET', subpath: 'auth/ping', return_error: true)[:http]
-            return nil if res_http['Location'].nil?
+            return if res_http['Location'].nil?
             redirect_uri = URI.parse(res_http['Location'])
             od = Api::AoC.split_org_domain(URI.parse(base_url))
-            return nil unless redirect_uri.path.end_with?("oauth2/#{od[:organization]}/login")
+            return unless redirect_uri.path.end_with?("oauth2/#{od[:organization]}/login")
             # either in standard domain, or product name in page
             return {
               version: Api::AoC.saas_url?(base_url) ? 'SaaS' : 'Self-managed',
@@ -150,14 +152,14 @@ module Aspera
               formatter.display_status('We will use web authentication to bootstrap.')
               auto_set_pub_key = true
               auto_set_jwt = true
-              raise 'TODO'
+              Aspera.error_not_implemented
               # 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')
             if auto_set_pub_key
-              Aspera.assert(myself['public_key'].empty?, exception_class: Cli::Error){'Public key is already set in profile (use --override=yes)'} unless option_override
+              Aspera.assert(myself['public_key'].empty?, type: 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
@@ -181,6 +183,38 @@ module Aspera
               test_args:    'user profile show'
             }
           end
+
+          # @param base [String] Base folder path
+          # @return [String] Folder path that does jot exist, with possible .<number> extension
+          def next_available_folder(base, always: false)
+            counter = always ? 1 : 0
+            loop do
+              result = counter.zero? ? base : "#{base}.#{counter}"
+              return result unless Dir.exist?(result)
+              counter += 1
+            end
+          end
+
+          # Get folder path that does not exist
+          # If it exists, an extension is added
+          # or a sequential number if extension == :seq
+          # @param folder [String] base folder
+          def unique_folder(folder, extension: nil, always: false)
+            case extension
+            when nil
+              folder
+            when :seq
+              # reuse helper
+              next_available_folder(folder, always: always)
+            else
+              if Dir.exist?(folder) || always
+                # NOTE: it might already exist
+                "#{folder}.#{Environment.instance.sanitized_filename(extension)}"
+              else
+                folder
+              end
+            end
+          end
         end
 
         def initialize(**_)
@@ -191,22 +225,29 @@ 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]}"
@@ -249,7 +290,7 @@ module Aspera
         # @return identifier
         def get_resource_id_from_args(resource_class_path)
           return instance_identifier do |field, value|
-            Aspera.assert(field.eql?('name'), exception_class: Cli::BadArgument){'only selection by name is supported'}
+            Aspera.assert(field.eql?('name'), type: Cli::BadArgument){'only selection by name is supported'}
             aoc_api.lookup_by_name(resource_class_path, value)['id']
           end
         end
@@ -262,7 +303,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] {items: , total: }
-        def api_call_paging(base_query={})
+        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
@@ -298,7 +339,7 @@ module Aspera
 
         # read using the query and paging
         # @return [Hash] {data: , total: }
-        def api_read_all(resource_class_path, base_query={})
+        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' => Rest::MIME_JSON}, query: query)
           end
@@ -324,7 +365,7 @@ module Aspera
         def resolve_dropbox_name_default_ws_id(query)
           if query.key?('dropbox_name')
             # convenience: specify name instead of id
-            raise 'Use field dropbox_name or dropbox_id, not both' if query.key?('dropbox_id')
+            raise BadArgument, '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.delete('dropbox_name'))['id']
           end
@@ -333,6 +374,8 @@ module Aspera
           query['exclude_dropbox_packages'] = !query.key?('dropbox_id') unless query.key?('exclude_dropbox_packages')
         end
 
+        # List all packages according to `query` option.
+        # @param <none>
         # @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: {})
@@ -354,7 +397,7 @@ module Aspera
             **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)
+          node_plugin = Node.new(context: context, api: top_node_api)
           case command_repo
           when *Node::COMMANDS_GEN4
             return node_plugin.execute_command_gen4(command_repo, file_id)
@@ -393,8 +436,9 @@ module Aspera
             return Main.result_transfer(transfer.start(server_apfid[:api].transfer_spec_gen4(
               server_apfid[:file_id],
               client_direction,
-              add_ts)))
-          else Aspera.error_unreachable_line
+              add_ts
+            )))
+          else Aspera.error_unexpected_value(command_repo){'command'}
           end
           Aspera.error_unreachable_line
         end
@@ -443,7 +487,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')
@@ -459,12 +505,12 @@ module Aspera
             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|
+            return do_bulk_operation(command: command, values: res_id) do |one_id|
               aoc_api.update("#{resource_class_path}/#{one_id}", changes)
               {'id' => one_id}
             end
           when :delete
-            return do_bulk_operation(command: command, descr: 'identifier', values: res_id) do |one_id|
+            return do_bulk_operation(command: command, values: res_id) do |one_id|
               aoc_api.delete("#{resource_class_path}/#{one_id}")
               {'id' => one_id}
             end
@@ -486,8 +532,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
@@ -501,7 +547,7 @@ module Aspera
             when :list
               return result_list('admin/auth_providers')
             when :update
-              raise 'not implemented'
+              Aspera.error_not_implemented
             end
           when :subscription
             org = aoc_api.read('organization')
@@ -603,12 +649,16 @@ module Aspera
               # cspell:enable
               result = bss_graphql.create(
                 nil,
-                {query:     graphql_query,
-                 variables: {
-                   organization_id: org['id'],
-                   aggregate:       aggregate,
-                   startDate:       start_date,
-                   endDate:         end_date}})['data']
+                {
+                  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
@@ -616,13 +666,13 @@ module Aspera
               base_url: "#{aoc_api.base_url}/admin/ats/pub/v1",
               auth:     {scope: Api::AoC::SCOPE_FILES_ADMIN_USER}
             }))
-            return Ats.new(**init_params).execute_action_gen(ats_api)
+            return Ats.new(context: context).execute_action_gen(ats_api)
           when :analytics
             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])
+            command_analytics = options.get_next_command(%i[application_events transfers files])
             case command_analytics
             when :application_events
               event_type = command_analytics.to_s
@@ -630,15 +680,15 @@ module Aspera
               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])
-              filter_id = options.get_next_argument('identifier', mandatory: false) ||
-                case filter_resource
+              event_resource_type = options.get_next_argument('resource', accept_list: %i[organizations users nodes])
+              event_resource_id = options.get_next_argument("#{event_resource_type} identifier", mandatory: false) ||
+                case event_resource_type
                 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
+                when :nodes then aoc_api.current_user_info['read_only_home_node_id']
                 else Aspera.error_unreachable_line
                 end
-              filter = options.get_option(:query) || {}
+              filter = query_read_delete(default: {})
               filter['limit'] ||= 100
               if options.get_option(:once_only, mandatory: true)
                 aoc_api.context = :files
@@ -650,18 +700,17 @@ module Aspera
                     'aoc_ana_date',
                     options.get_option(:url, mandatory: true),
                     aoc_api.workspace[:name],
-                    filter_resource.to_s,
-                    filter_id
-                  ]))
+                    event_resource_type.to_s,
+                    event_resource_id
+                  ])
+                )
                 start_date_time = saved_date.first
                 stop_date_time = Time.now.utc.strftime('%FT%T.%LZ')
-                # Log.log().error("start: #{start_date_time}")
-                # Log.log().error("end:   #{stop_date_time}")
                 saved_date[0] = stop_date_time
                 filter['start_time'] = start_date_time unless start_date_time.nil?
                 filter['stop_time'] = stop_date_time
               end
-              events = analytics_api.read("#{filter_resource}/#{filter_id}/#{event_type}", query_read_delete(default: filter))[event_type]
+              events = analytics_api.read("#{event_resource_type}/#{event_resource_id}/#{event_type}", filter)[event_type]
               start_date_persistency&.save
               if !options.get_option(:notify_to).nil?
                 events.each do |tr_event|
@@ -669,6 +718,22 @@ module Aspera
                 end
               end
               return Main.result_object_list(events)
+            when :files
+              event_type = command_analytics.to_s
+              event_resource_type = options.get_next_argument('resource', accept_list: %i[organizations users nodes])
+              event_resource_id = instance_identifier(description: "#{event_resource_type} identifier")
+              event_resource_id =
+                case event_resource_type
+                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['read_only_home_node_id']
+                else Aspera.error_unreachable_line
+                end if event_resource_id.empty?
+              event_uuid = instance_identifier(description: 'event uuid')
+              filter = query_read_delete(default: {})
+              filter['limit'] ||= 100
+              events = analytics_api.read("#{event_resource_type}/#{event_resource_id}/transfers/#{event_uuid}/#{event_type}", filter)[event_type]
+              return Main.result_object_list(events)
             end
           when :usage_reports
             aoc_api.context = :files
@@ -692,20 +757,21 @@ module Aspera
           when :private then 'shared_folder_auth_link'
           else Aspera.error_unreachable_line
           end
-          case options.get_next_command(%i[create delete list])
+          command = options.get_next_command(%i[create delete list show modify])
+          case command
           when :create
-            creation_params = {
+            entity_data = {
               purpose:            purpose_local,
               user_selected_name: nil
             }
             case link_type
             when :private
-              creation_params[:data] = shared_data
+              entity_data[:data] = shared_data
             when :public
-              creation_params[:expires_at]       = nil
-              creation_params[:password_enabled] = false
+              entity_data[:expires_at]       = nil
+              entity_data[:password_enabled] = false
               shared_data[:name] = ''
-              creation_params[:data] = {
+              entity_data[:data] = {
                 aoc:            true,
                 url_token_data: {
                   data:    shared_data,
@@ -713,11 +779,17 @@ module Aspera
                 }
               }
             end
-            result_create_short_link = aoc_api.create('short_links', creation_params)
+            custom_data = value_create_modify(command: command, default: {})
+            if (pass = custom_data.delete('password'))
+              entity_data[:data][:url_token_data][:password] = pass
+              entity_data[:password_enabled] = true
+            end
+            entity_data.deep_merge!(custom_data)
+            result_create_short_link = aoc_api.create('short_links', entity_data)
             # public: Creation: permission on node
             yield(result_create_short_link['resource_id']) if block_given? && link_type.eql?(:public)
             return Main.result_single_object(result_create_short_link)
-          when :list
+          when :list, :show
             query = if link_type.eql?(:private)
               shared_data
             else
@@ -735,7 +807,31 @@ module Aspera
               # embed: 'updated_by_user',
               sort:        '-created_at'
             }
-            return result_list('short_links', fields: Formatter.all_but('data'), base_query: list_params)
+            return result_list('short_links', fields: Formatter.all_but('data'), base_query: list_params) if command.eql?(:list)
+            one_id = instance_identifier
+            found = api_read_all('short_links', list_params)[:items].find{ |item| item['id'].eql?(one_id)}
+            raise Cli::BadIdentifier.new('Short link', one_id) if found.nil?
+            return Main.result_single_object(found, fields: Formatter.all_but('data'))
+          when :modify
+            raise Cli::BadArgument, 'Only public links can be modified' unless link_type.eql?(:public)
+            node_file = shared_data.slice(:node_id, :file_id)
+            entity_data = {
+              data:       {
+                url_token_data: {
+                  data: node_file
+                }
+              },
+              json_query: node_file
+            }
+            one_id = instance_identifier
+            custom_data = value_create_modify(command: command, default: {})
+            if (pass = custom_data.delete('password'))
+              entity_data[:data][:url_token_data][:password] = pass
+              entity_data[:password_enabled] = true
+            end
+            entity_data.deep_merge!(custom_data)
+            aoc_api.update("short_links/#{one_id}", entity_data)
+            return Main.result_status('modified')
           when :delete
             one_id = instance_identifier
             shared_data.delete(:workspace_id)
@@ -754,7 +850,7 @@ module Aspera
 
         # @return persistency object if option `once_only` is used.
         def package_persistency
-          return nil unless options.get_option(:once_only, mandatory: true)
+          return unless options.get_option(:once_only, mandatory: true)
           # TODO: add query info to id
           PersistencyActionOnce.new(
             manager: persistency,
@@ -762,8 +858,9 @@ module Aspera
             id: IdGenerator.from_list(
               ['aoc_recv',
                options.get_option(:url, mandatory: true),
-               aoc_api.workspace[:id]
-              ].concat(aoc_api.additional_persistence_ids)))
+               aoc_api.workspace[:id]].concat(aoc_api.additional_persistence_ids)
+            )
+          )
         end
 
         def reject_packages_from_persistency(all_packages, skip_ids_persistency)
@@ -801,7 +898,9 @@ module Aspera
           when :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 Main.result_object_list(aoc_api.read('client_settings/'))
             when :workspaces
@@ -831,7 +930,7 @@ module Aspera
               end
             end
           when :packages
-            package_command = options.get_next_command(%i[shared_inboxes send receive list show delete].concat(Node::NODE4_READ_ACTIONS), aliases: {recv: :receive})
+            package_command = options.get_next_command(%i[shared_inboxes send receive list show delete modify].concat(Node::NODE4_READ_ACTIONS), aliases: {recv: :receive})
             case package_command
             when :shared_inboxes
               case options.get_next_command(%i[list show short_link])
@@ -853,7 +952,7 @@ module Aspera
               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 user auth and link auth
+              # 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])
@@ -862,7 +961,7 @@ module Aspera
                 # enforce workspace id from link (should be already ok, but in case user wanted to override)
                 package_data['workspace_id'] = aoc_api.public_link['data']['workspace_id']
               end
-
+              package_data['encryption_at_rest'] = true if transfer.option_transfer_spec['content_protection'].eql?('encrypt')
               # transfer may raise an error
               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]))
@@ -872,50 +971,70 @@ module Aspera
               ids_to_download = nil
               if !aoc_api.public_link.nil?
                 aoc_api.assert_public_link_types(['view_received_package'])
-                # set the package id from link
+                # 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
+              # Get from command line unless it was a public link
               ids_to_download ||= instance_identifier
               skip_ids_persistency = package_persistency
               case ids_to_download
-              when SpecialValues::ALL, SpecialValues::INIT
+              when SpecialValues::INIT
+                all_packages = list_all_packages_with_query[:items]
+                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)")
+              when SpecialValues::ALL
                 all_packages = list_all_packages_with_query[:items]
-                if ids_to_download.eql?(SpecialValues::INIT)
-                  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
                 # 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_def = options.get_option(:package_folder)
+              unless per_package_def.nil?
+                raise Cli::BadArgument, "Invalid package folder option : #{per_package_def}" unless per_package_def =~ /\A([^+]+)(?:\+([^?]+)(\?)?)?\z/
+                per_package_field1 = Regexp.last_match(1)
+                per_package_field2 = Regexp.last_match(2)
+                per_package_sub_always = Regexp.last_match(3).nil?
+              end
+              # get value outside of loop
+              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'],
                   package_info: package_info,
-                  **workspace_id_hash(name: true))
+                  **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}
+                )
+                unless per_package_def.nil?
+                  # folder based on first field
+                  folder = File.join(
+                    destination_folder,
+                    Environment.instance.sanitized_filename(package_info[per_package_field1])
+                  )
+                  transfer.option_transfer_spec['destination_root'] = self.class.unique_folder(
+                    folder,
+                    extension: per_package_field2.eql?('seq') ? :seq : package_info[per_package_field2],
+                    always: per_package_sub_always
+                  )
+                end
+                formatter.display_status(%Q{Downloading package: [#{package_info['id']}] "#{package_info['name']}" to [#{destination_folder}]})
                 statuses = transfer.start(
-                  package_node_api.transfer_spec_gen4(
-                    package_info['contents_file_id'],
-                    Transfer::Spec::DIRECTION_RECEIVE,
-                    {'paths'=> file_list}),
-                  rest_token: package_node_api)
+                  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 skip_ids_persistency && TransferAgent.session_status(statuses).eql?(:success)
@@ -936,10 +1055,15 @@ module Aspera
               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|
+              return do_bulk_operation(command: package_command, values: instance_identifier) do |id|
                 Aspera.assert_values(id.class, [String, Integer]){'identifier'}
                 aoc_api.delete("packages/#{id}")
               end
+            when :modify
+              id = instance_identifier
+              package_data = value_create_modify(command: package_command)
+              aoc_api.update("packages/#{id}", package_data)
+              return Main.result_status('modified')
             when *Node::NODE4_READ_ACTIONS
               package_id = instance_identifier
               package_info = aoc_api.read("packages/#{package_id}")
@@ -954,7 +1078,8 @@ module Aspera
               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_hash(name: true))
+                **workspace_id_hash(name: true)
+              )
               shared_apfid = home_node_api.resolve_api_fid(aoc_api.home[:file_id], folder_dest)
               return short_link_command(
                 purpose_public: 'view_shared_file',
@@ -992,12 +1117,16 @@ module Aspera
             command_automation = options.get_next_command(%i[workflows instances])
             case command_automation
             when :instances
-              return entity_action(aoc_api, 'workflow_instances')
+              return entity_execute(api: aoc_api, entity: 'workflow_instances')
             when :workflows
               wf_command = options.get_next_command(%i[action launch].concat(Plugin::ALL_OPS))
               case wf_command
               when *Plugin::ALL_OPS
-                return entity_command(wf_command, automation_api, 'workflows')
+                return entity_execute(
+                  api: automation_api,
+                  entity: 'workflows',
+                  command: wf_command
+                )
               when :launch
                 wf_id = instance_identifier
                 data = automation_api.create("workflows/#{wf_id}/launch", {})