aspera-cli 4.25.1 → 4.25.3

data/bin/asession

@@ -6,95 +6,118 @@ require 'aspera/agent/direct'
 require 'aspera/cli/extended_value'
 require 'aspera/products/transferd'
 require 'aspera/log'
+require 'aspera/assert'
 require 'json'
-# Extended transfer spec parameter (only used in asession)
-PARAM_SPEC = 'spec'
-# Log level
-PARAM_LOG_LEVEL = 'loglevel'
-# Transfer agent options
-PARAM_AGENT = 'agent'
-# By default go to /tmp/username.filelist
-PARAM_TMP_FILE_LIST_FOLDER = 'file_list_folder'
-PARAM_SDK = 'sdk'
-# Place transfer spec in that
-SAMPLE_DEMO = '"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"demoaspera"'
-SAMPLE_DEMO2 = '"direction":"receive","destination_root":"./test.dir"'
-def assert_usage(assertion, error_message)
-  return if assertion
-  # rubocop:disable Style/StderrPuts
-  $stderr.puts('ERROR: '.red.blink + error_message) if error_message
-  $stderr.puts('USAGE')
-  $stderr.puts('    asession')
-  $stderr.puts('    asession -h|--help')
-  $stderr.puts('    asession [<session spec extended value>]')
-  $stderr.puts('    ')
-  $stderr.puts('    If no argument is provided, default will be used: @json:@stdin')
-  $stderr.puts('    -h, --help display this message')
-  $stderr.puts('    <session spec extended value> a dictionary (Hash)')
-  $stderr.puts('    The value can be either:')
-  $stderr.puts("       the JSON description itself, e.g. @json:'{\"xx\":\"yy\",...}'")
-  $stderr.puts('       @json:@stdin, if the JSON is provided from stdin')
-  $stderr.puts('       @json:@file:<path>, if the JSON is provided from a file')
-  $stderr.puts('    The following keys are recognized in session spec:')
-  $stderr.puts("       #{PARAM_SPEC} : mandatory, contains the transfer spec")
-  $stderr.puts("       #{PARAM_LOG_LEVEL} : modify log level (to stderr)")
-  $stderr.puts("       #{PARAM_AGENT} : modify transfer agent parameters, e.g. ascp_args")
-  $stderr.puts("       #{PARAM_TMP_FILE_LIST_FOLDER} : location of temporary files")
-  $stderr.puts("       #{PARAM_SDK} : location of SDK (ascp)")
-  $stderr.puts('    Asynchronous commands can be provided on STDIN, examples:')
-  $stderr.puts('       {"type":"START","source":"/aspera-test-dir-tiny/200KB.2"}')
-  $stderr.puts('       {"type":"START","source":"xx","destination":"yy"}')
-  $stderr.puts('       {"type":"DONE"}')
-  $stderr.puts('EXAMPLES')
-  $stderr.puts(%Q(    asession @json:'{"#{PARAM_SPEC}":{#{SAMPLE_DEMO},#{SAMPLE_DEMO2},"paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}]}}'))
-  $stderr.puts(%Q(    echo '{"#{PARAM_SPEC}":{"remote_host":...}}'|asession @json:@stdin))
-  # rubocop:enable Style/StderrPuts
-  Process.exit(0)
-end
-parameter_source_err_msg = ' (argument), did you specify: "@json:" ?'
-# By default assume JSON input on stdin if no argument
-if ARGV.empty?
-  ARGV.push('@json:@stdin')
-  parameter_source_err_msg = ' (JSON on stdin)'
+
+class UsageError < StandardError; end
+
+class SimpleTransferManager
+  # First level parameters in session spec
+  # - Extended transfer spec parameter (only used in asession)
+  PARAM_SPEC = 'spec'
+  # - Log level
+  PARAM_LOG_LEVEL = 'loglevel'
+  # - Transfer agent options
+  PARAM_AGENT = 'agent'
+  # - By default go to /tmp/username.filelist
+  PARAM_TMP_FILE_LIST_FOLDER = 'file_list_folder'
+  # - SDK location
+  PARAM_SDK = 'sdk'
+  # Default SDK location
+  SDK_DEFAULT_DIR = File.join(Dir.home, '.aspera', 'sdk')
+  # Place transfer spec in that
+  SAMPLE_DEMO = '"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"demoaspera"'
+  SAMPLE_DEMO2 = '"direction":"receive","destination_root":"./test.dir"'
+  STDIN_INPUT = '@json:@stdin:'
+  class << self
+    # Assert usage condition, otherwise display usage message and exit
+    # @param assertion [Boolean] Assertion to verify
+    # @param error_message [String] Error message to display
+    def usage
+      # rubocop:disable Style/StderrPuts
+      $stderr.puts('USAGE')
+      $stderr.puts('    asession')
+      $stderr.puts('    asession -h|--help')
+      $stderr.puts('    asession [<session spec extended value>]')
+      $stderr.puts('    ')
+      $stderr.puts('    If no argument is provided, default will be used: @json:@stdin')
+      $stderr.puts('    -h, --help display this message')
+      $stderr.puts('    <session spec extended value> a dictionary (Hash)')
+      $stderr.puts('    The value can be either:')
+      $stderr.puts("       the JSON description itself, e.g. @json:'{\"xx\":\"yy\",...}'")
+      $stderr.puts('       @json:@stdin, if the JSON is provided from stdin')
+      $stderr.puts('       @json:@file:<path>, if the JSON is provided from a file')
+      $stderr.puts('    The following keys are recognized in session spec:')
+      $stderr.puts("       #{PARAM_SPEC} : mandatory, contains the transfer spec")
+      $stderr.puts("       #{PARAM_LOG_LEVEL} : modify log level (to stderr)")
+      $stderr.puts("       #{PARAM_AGENT} : modify transfer agent parameters, e.g. ascp_args")
+      $stderr.puts("       #{PARAM_TMP_FILE_LIST_FOLDER} : location of temporary files")
+      $stderr.puts("       #{PARAM_SDK} : location of SDK (ascp)")
+      $stderr.puts('    Asynchronous commands can be provided on STDIN, examples:')
+      $stderr.puts('       {"type":"START","source":"/aspera-test-dir-tiny/200KB.2"}')
+      $stderr.puts('       {"type":"START","source":"xx","destination":"yy"}')
+      $stderr.puts('       {"type":"DONE"}')
+      $stderr.puts('EXAMPLES')
+      $stderr.puts(%Q(    asession @json:'{"#{PARAM_SPEC}":{#{SAMPLE_DEMO},#{SAMPLE_DEMO2},"paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}]}}'))
+      $stderr.puts(%Q(    echo '{"#{PARAM_SPEC}":{"remote_host":...}}'|asession #{STDIN_INPUT}))
+      # rubocop:enable Style/StderrPuts
+    end
+  end
+  def initialize(args)
+    parameter_source_err_msg = ' (argument), did you specify: "@json:" ?'
+    # By default assume JSON input on stdin if no argument
+    if args.empty?
+      args.push(STDIN_INPUT)
+      parameter_source_err_msg = ' (JSON on stdin)'
+    end
+    # Anyway expect only one argument: session information
+    Aspera.assert(args.length.eql?(1), 'exactly one argument is expected', type: UsageError)
+    if ['-h', '--help'].include?(args.first)
+      SimpleTransferManager.usage
+      exit(0)
+    end
+    # Parse transfer spec
+    @session_spec = Aspera::Cli::ExtendedValue.instance.evaluate(args.pop, context: 'asession parameter')
+    # Ensure right type for parameter
+    Aspera.assert(@session_spec.is_a?(Hash), "The value must be a Hash#{parameter_source_err_msg}", type: UsageError)
+    Aspera.assert(@session_spec[PARAM_SPEC].is_a?(Hash), "The value must contain key #{PARAM_SPEC} with Hash value", type: UsageError)
+    # Additional debug capability
+    Aspera::Log.instance.level = @session_spec[PARAM_LOG_LEVEL].to_sym if @session_spec.key?(PARAM_LOG_LEVEL)
+    # Possibly override temp folder
+    Aspera::Transfer::Parameters.file_list_folder = @session_spec[PARAM_TMP_FILE_LIST_FOLDER] if @session_spec.key?(PARAM_TMP_FILE_LIST_FOLDER)
+    Aspera::Products::Transferd.sdk_directory = @session_spec[PARAM_SDK] || SDK_DEFAULT_DIR
+    agent_params = @session_spec[PARAM_AGENT] || {}
+    agent_params['quiet'] = true
+    agent_params['management_cb'] = ->(event) do
+      puts JSON.generate(Aspera::Ascp::Management.event_native_to_snake(event))
+    end
+    # Get local agent (ascp), disable ascp output on stdout to not mix with JSON events
+    @client = Aspera::Agent::Direct.new(**agent_params.symbolize_keys)
+  end
+
+  def start
+    # Start transfer (asynchronous)
+    @client.start_transfer(@session_spec[PARAM_SPEC])
+    # commands to ascp on mgt port
+    Thread.new do
+      loop do
+        data = JSON.parse($stdin.gets)
+        @client.send_command(data)
+      end
+    rescue => e
+      Aspera::Log.log.error("Error reading commands from stdin: #{e.message}")
+      Process.exit(1)
+    end
+    # No exit code: status is success (0)
+    @client.wait_for_transfers_completion
+    @client.shutdown
+  end
 end
-# Anyway expect only one argument: session information
-assert_usage(ARGV.length.eql?(1), 'exactly one argument is expected')
-assert_usage(!['-h', '--help'].include?(ARGV.first), nil)
-# Parse transfer spec
+
 begin
-  session_argument = ARGV.pop
-  session_spec = Aspera::Cli::ExtendedValue.instance.evaluate(session_argument)
-rescue
-  assert_usage(false, "Cannot parse argument: #{session_argument}")
-end
-# Ensure right type for parameter
-assert_usage(session_spec.is_a?(Hash), "The value must be a Hash#{parameter_source_err_msg}")
-assert_usage(session_spec[PARAM_SPEC].is_a?(Hash), "The value must contain key #{PARAM_SPEC} with Hash value")
-# Additional debug capability
-Aspera::Log.instance.level = session_spec[PARAM_LOG_LEVEL].to_sym if session_spec.key?(PARAM_LOG_LEVEL)
-# Possibly override temp folder
-Aspera::Transfer::Parameters.file_list_folder = session_spec[PARAM_TMP_FILE_LIST_FOLDER] if session_spec.key?(PARAM_TMP_FILE_LIST_FOLDER)
-session_spec[PARAM_SDK] = File.join(Dir.home, '.aspera', 'sdk') unless session_spec.key?(PARAM_SDK)
-Aspera::Products::Transferd.sdk_directory = session_spec[PARAM_SDK]
-session_spec[PARAM_AGENT] = {} unless session_spec.key?(PARAM_AGENT)
-agent_params = session_spec[PARAM_AGENT]
-agent_params['quiet'] = true
-agent_params['management_cb'] = ->(event) do
-  puts JSON.generate(Aspera::Ascp::Management.event_native_to_snake(event))
-end
-# Get local agent (ascp), disable ascp output on stdout to not mix with JSON events
-client = Aspera::Agent::Direct.new(**agent_params.symbolize_keys)
-# Start transfer (asynchronous)
-client.start_transfer(session_spec[PARAM_SPEC])
-# commands to ascp on mgt port
-Thread.new do
-  loop do
-    data = JSON.parse($stdin.gets)
-    client.send_command(data)
-  end
-rescue
-  Process.exit(1)
+  SimpleTransferManager.new(ARGV).start
+rescue UsageError => e
+  Aspera::Log.log.error(e.message)
+  SimpleTransferManager.usage
+  exit(1)
 end
-# No exit code: status is success (0)
-client.wait_for_transfers_completion
-client.shutdown

data/lib/aspera/agent/connect.rb

@@ -32,7 +32,7 @@ module Aspera
             headers: {'Origin' => RestParameters.instance.user_agent}
           )
           connect_info = @connect_api.read('info/version')
-          Log.log.info('Connect was reached') if method_index > 0
+          Log.log.debug('Connect was reached') if method_index > 0
           Log.dump(:connect_version, connect_info)
         rescue StandardError => e # Errno::ECONNREFUSED
           Log.log.debug{"Exception: #{e}"}

data/lib/aspera/agent/desktop.rb

@@ -30,7 +30,7 @@ module Aspera
           @client_app_api = Aspera::JsonRpcClient.new(Aspera::Rest.new(base_url: aspera_client_api_url))
           client_info = @client_app_api.get_info
           Log.dump(:client_version, client_info)
-          Log.log.info('Client was reached') if method_index > 0
+          Log.log.debug('Client was reached') if method_index > 0
         rescue Errno::ECONNREFUSED => e
           start_url = START_URIS[method_index]
           method_index += 1

data/lib/aspera/agent/direct.rb

@@ -16,9 +16,9 @@ require 'English'
 
 module Aspera
   module Agent
-    # executes a local "ascp", create mgt port
+    # Execute a local `ascp` and use its management port to monitor progress
     class Direct < Base
-      # ascp started locally, so listen local
+      # `ascp` started locally, so listen local
       LISTEN_LOCAL_ADDRESS = '127.0.0.1'
       # 0 means: use any available port
       SELECT_AVAILABLE_PORT = 0
@@ -48,13 +48,13 @@ module Aspera
         spawn_timeout_sec: 2,
         spawn_delay_sec:   2,
         multi_incr_udp:    nil,
-        resume:            nil,
+        resume:            {},
         monitor:           true,
         management_cb:     nil,
         **base_options
       )
         super(**base_options)
-        # Special transfer parameters provided
+        # Options that have impact on `ascp` command line generated
         @tr_opts = {
           ascp_args:       ascp_args,
           wss:             wss,
@@ -69,7 +69,6 @@ module Aspera
         @multi_incr_udp = multi_incr_udp.nil? ? Environment.instance.os.eql?(Environment::OS_WINDOWS) : multi_incr_udp
         @monitor = monitor
         @management_cb = management_cb
-        resume = {} if resume.nil?
         Aspera.assert_type(resume, Hash){'resume'}
         @resume_policy = Transfer::Resumer.new(**resume.symbolize_keys)
         # all transfer jobs, key = SecureRandom.uuid, protected by mutex, cond var on change
@@ -78,6 +77,7 @@ module Aspera
         @mutex = Mutex.new
         @pre_calc_sent = false
         @pre_calc_last_size = nil
+        # Check on all management messages if that file exists, and if so, read commands from it
         @command_file = File.join(config_dir || '.', "send_#{$PROCESS_ID}")
       end
 
@@ -115,7 +115,7 @@ module Aspera
             Log.log.debug('multi_session count is zero: no multi session')
             multi_session_info = nil
           elsif @multi_incr_udp # multi_session_info[:count] > 0
-            # if option not true: keep default udp port for all sessions
+            # if option not `true`: keep default UDP port for all sessions
             multi_session_info[:udp_base] = transfer_spec.key?('fasp_port') ? transfer_spec['fasp_port'] : Transfer::Spec::UDP_PORT
             # delete from original transfer spec, as we will increment values
             transfer_spec.delete('fasp_port')
@@ -225,9 +225,9 @@ module Aspera
             start_and_monitor_process(session: session, **session[:env_args])
           end
           Log.log.debug('transfer ok'.bg_green)
-        rescue StandardError => e
+        rescue => e
           session[:error] = e
-          Log.log.error{"Transfer thread error: #{e.class}:\n#{e.message}:\n#{e.backtrace.join("\n")}".red} if Log.instance.level.eql?(:debug)
+          raise if Log.log.debug? || !e.is_a?(Transfer::Error)
         end
         Log.log.debug{"EXIT (#{Thread.current[:name]})"}
       end
@@ -242,7 +242,7 @@ module Aspera
       # @param env     [Hash]   Environment variables (comes from ascp_args)
       # @param args    [Array]  Command line arguments (comes from ascp_args)
       # @return [nil] when process has exited
-      # @throw FaspError on error
+      # @raise FaspError on error
       def start_and_monitor_process(
         session:,
         name:,
@@ -251,15 +251,15 @@ module Aspera
       )
         Aspera.assert_type(session, Hash)
         notify_progress(:sessions_init, info: 'starting')
+        # Do not use `capture_stderr`
+        capture_stderr = false
+        stderr_r, stderr_w = nil
+        spawn_args = {}
+        command_pid = nil
+        # Get location of command executable (ascp, async)
+        command_path = Ascp::Installation.instance.path(name)
+        command_arguments = [command_path]
         begin
-          # do not use
-          capture_stderr = false
-          stderr_r, stderr_w = nil
-          spawn_args = {}
-          command_pid = nil
-          # get location of command executable (ascp, async)
-          command_path = Ascp::Installation.instance.path(name)
-          command_arguments = [command_path]
           if @monitor
             # we use Socket directly, instead of TCPServer, as it gives access to lower level options
             socket_class = defined?(JRUBY_VERSION) ? ServerSocket : Socket
@@ -353,7 +353,7 @@ module Aspera
             Process.kill(:INT, command_pid) if @monitor && !Environment.instance.os.eql?(Environment::OS_WINDOWS)
             # collect process exit status or wait for termination
             _, status = Process.wait2(command_pid)
-            if stderr_r
+            if capture_stderr
               # process stderr of ascp
               stderr_flag = false
               stderr_r.each_line do |line|
@@ -379,6 +379,7 @@ module Aspera
 
       private
 
+      # [Array<Hash>] List of sessions, one per `ascp` process
       attr_reader :sessions
 
       # Notify progress to callback

data/lib/aspera/agent/node.rb

@@ -77,7 +77,7 @@ module Aspera
           # status is empty sometimes with status 200...
           transfer_data = node_api_.read("ops/transfers/#{@transfer_id}") || {'status' => 'unknown'} rescue {'status' => 'waiting(api error)'}
           case transfer_data['status']
-          when 'waiting', 'partially_completed', 'unknown', 'waiting(read error)'
+          when 'waiting', 'partially_completed', 'unknown', 'waiting(read error)', 'waiting(api error)'
             notify_progress(:sessions_init, info: transfer_data['status'])
           when 'running'
             if !session_started

data/lib/aspera/api/aoc.rb

@@ -17,7 +17,7 @@ module Aspera
       DEFAULT_WORKSPACE = ''
       # Production domain of AoC
       SAAS_DOMAIN_PROD = 'ibmaspera.com' # cspell:disable-line
-      # to avoid infinite loop in pub link redirection
+      # To avoid infinite loop in pub link redirection
       MAX_AOC_URL_REDIRECT = 10
       CLIENT_ID_PREFIX = 'aspera.'
       # Well-known AoC global client apps
@@ -47,7 +47,7 @@ module Aspera
         :PERMISSIONS_CREATED,
         :ID_AK_ADMIN
 
-      # various API scopes supported
+      # Various API scopes supported
       module Scope
         SELF = 'self'
         USER = 'user:all'
@@ -142,11 +142,14 @@ module Aspera
           }
         end
 
-        # Call block with same query using paging and response information.
-        # Block must return an Array with data and http response
-        # @return [Hash] {items: , total: }
-        def call_paging(query: nil, formatter: nil)
-          query = {} if query.nil?
+        # Call `block` with same query using paging and response information.
+        # Block must return a 2 element `Array` with data and http response
+        # @param query    [Hash] Additionnal query parameters
+        # @param progress [nil, Object] Uses methods: `long_operation_running` and `long_operation_terminated`
+        # @return [Hash] Items and total number of items
+        # @option return [Array<Hash>] :items The list of items
+        # @option return [Integer] :total The total number of items
+        def call_paging(query: {}, progress: nil)
           Aspera.assert_type(query, Hash){'query'}
           Aspera.assert(block_given?)
           # set default large page if user does not specify own parameters. AoC Caps to 1000 anyway
@@ -174,9 +177,9 @@ module Aspera
             break if !max_items.nil? && item_list.count >= max_items
             break if !max_pages.nil? && page_count >= max_pages
             break if total_count&.<=(item_list.count)
-            formatter&.long_operation_running("#{item_list.count} / #{total_count}") unless total_count.eql?(item_list.count.to_s)
+            progress&.long_operation_running("#{item_list.count} / #{total_count}") unless total_count.eql?(item_list.count.to_s)
           end
-          formatter&.long_operation_terminated
+          progress&.long_operation_terminated
           item_list = item_list[0..max_items - 1] if !max_items.nil? && item_list.count > max_items
           return {items: item_list, total: total_count}
         end
@@ -195,6 +198,23 @@ module Aspera
         def workspace_access?(permission)
           permission['access_id'].start_with?("#{ID_AK_ADMIN}_WS_")
         end
+
+        # Expand access levels to full list of levels.
+        # @param levels [nil, String, Array] Access levels
+        # @return [Array] Expanded access levels
+        def expand_access_levels(levels)
+          case levels
+          when nil, 'edit' then Node::ACCESS_LEVELS
+          when 'preview' then %w[list preview]
+          when 'download' then %w[list preview read]
+          when 'upload' then %w[mkdir write]
+          when Array
+            Aspera.assert_array_all(levels, String){'access_levels'}
+            levels.each{ |level| Aspera.assert_value(level, Node::ACCESS_LEVELS){'access_level'}}
+            levels
+          else Aspera.error_unexpected_value(levels){"access_levels must be a list of #{Node::ACCESS_LEVELS.join(', ')} or one of edit, preview, download, upload"}
+          end
+        end
       end
 
       attr_reader :private_link
@@ -212,7 +232,8 @@ module Aspera
         username: nil,
         password: nil,
         workspace: nil,
-        secret_finder: nil
+        secret_finder: nil,
+        progress_disp: nil
       )
         # Test here because link may set url
         Aspera.assert(url, 'Missing mandatory option: url', type: ParameterError)
@@ -223,6 +244,7 @@ module Aspera
         # key: access key
         # value: associated secret
         @secret_finder = secret_finder
+        @progress_disp = progress_disp
         @workspace_name = workspace
         @cache_user_info = nil
         @cache_url_token_info = nil
@@ -282,10 +304,12 @@ module Aspera
           )
       end
 
-      # read using the query and paging
+      # Read using the query and paging
+      # @param subpath [String] Entity path
+      # @param query [nil, Hash] Additional query
       # @return [Hash] {items: , total: }
-      def read_with_paging(subpath, query = nil, formatter: nil)
-        return self.class.call_paging(query: query, formatter: formatter) do |paged_query|
+      def read_with_paging(subpath, query = nil)
+        return self.class.call_paging(query: query, progress: @progress_disp) do |paged_query|
           read(subpath, query: paged_query, ret: :both)
         end
       end
@@ -316,9 +340,9 @@ module Aspera
         @cache_user_info =
           begin
             read('self')
-          rescue StandardError => e
-            raise e if exception
-            Log.log.debug{"ignoring error: #{e}"}
+          rescue Aspera::RestCallError => e
+            raise if exception || e.message.include?('invalid_grant')
+            Log.log.debug{"Ignoring error: (#{e.class}) #{e}"}
             {}
           end
         USER_INFO_FIELDS_MIN.each{ |f| @cache_user_info[f] = nil if @cache_user_info[f].nil?}
@@ -394,10 +418,10 @@ module Aspera
       # @param node_id        [String] identifier of node in AoC
       # @param workspace_id   [String,nil] workspace identifier
       # @param workspace_name [String,nil] workspace name
-      # @param scope          [String,nil] e.g. Node::SCOPE_USER, or Node::SCOPE_ADMIN, or nil (requires secret)
+      # @param scope          [String,nil] e.g. Node::Scope::USER, or Node::Scope::ADMIN, or nil (requires secret)
       # @param package_info   [Hash,nil] created package information
       # @returns [Node] a node API for access key
-      def node_api_from(node_id:, workspace_id: nil, workspace_name: nil, scope: Node::SCOPE_USER, package_info: nil)
+      def node_api_from(node_id:, workspace_id: nil, workspace_name: nil, scope: Node::Scope::USER, package_info: nil)
         Aspera.assert_type(node_id, String)
         node_info = read("nodes/#{node_id}")
         workspace_name = read("workspaces/#{workspace_id}")['name'] if workspace_name.nil? && !workspace_id.nil?
@@ -428,7 +452,7 @@ module Aspera
           node_params[:auth] = auth_params.clone
           node_params[:auth][:params] ||= {}
           node_params[:auth][:params][:scope] = Node.token_scope(node_info['access_key'], scope)
-          node_params[:auth][:params][:owner_access] = true if scope.eql?(Node::SCOPE_ADMIN)
+          node_params[:auth][:params][:owner_access] = true if scope.eql?(Node::Scope::ADMIN)
           # Special header required for bearer token only
           node_params[:headers] = {Node::HEADER_X_ASPERA_ACCESS_KEY => node_info['access_key']}
         end
@@ -693,7 +717,7 @@ module Aspera
         # (optional). The name of the folder to be displayed to the destination user.
         # Use it if its value is different from the "share_as" field.
         event_creation['link_name'] = app_info[:opt_link_name] unless app_info[:opt_link_name].nil?
-        create('events', event_creation)
+        create('events', event_creation, query: {admin: true})
       end
     end
   end

data/lib/aspera/api/faspex.rb

@@ -60,19 +60,32 @@ module Aspera
       PATH_AUTH = 'auth'
       PATH_API_V5 = 'api/v5'
       PATH_HEALTH = 'configuration/ping'
-      private_constant :PATH_API_V5,
-        :PATH_HEALTH,
-        :PATH_AUTH
+      private_constant :PATH_AUTH,
+        :PATH_API_V5,
+        :PATH_HEALTH
       RECIPIENT_TYPES = %w[user workgroup external_user distribution_list shared_inbox].freeze
       PACKAGE_TERMINATED = %w[completed failed].freeze
       # list of supported mailbox types (to list packages)
-      API_LIST_MAILBOX_TYPES = %w[inbox inbox_history inbox_all inbox_all_history outbox outbox_history pending pending_history all].freeze
+      SENT_MAILBOX_TYPES = %w[outbox outbox_history].freeze
+      API_LIST_MAILBOX_TYPES = (%w[inbox inbox_history inbox_all inbox_all_history pending pending_history all] + SENT_MAILBOX_TYPES).freeze
       # PACKAGE_SEND_FROM_REMOTE_SOURCE = 'remote_source'
       # Faspex API v5: get transfer spec for connect
       TRANSFER_CONNECT = 'connect'
       ADMIN_RESOURCES = %i[
-        accounts distribution_lists contacts jobs workgroups shared_inboxes nodes oauth_clients registrations saml_configs
-        metadata_profiles email_notifications alternate_addresses webhooks
+        accounts
+        distribution_lists
+        contacts
+        jobs
+        workgroups
+        shared_inboxes
+        nodes
+        oauth_clients
+        registrations
+        saml_configs
+        metadata_profiles
+        email_notifications
+        alternate_addresses
+        webhooks
       ].freeze
       # states for jobs not in final state
       JOB_RUNNING = %w[queued working].freeze
@@ -114,6 +127,12 @@ module Aspera
         def public_link?(url)
           url.include?('?context=')
         end
+
+        # Depending on box, the package files are either: `received` or `sent`
+        # @return [:sent, :received] the type of mailbox
+        def box_type(box)
+          SENT_MAILBOX_TYPES.include?(box) || box == 'ALL' ? :sent : :received
+        end
       end
       attr_reader :pub_link_context
 

data/lib/aspera/api/node.rb

@@ -16,9 +16,15 @@ module Aspera
   module Api
     # Provides additional functions using node API with gen4 extensions (access keys)
     class Node < Aspera::Rest
-      # Separator between node.AK and user:all
-      SCOPE_SEPARATOR = ':'
-      SCOPE_NODE_PREFIX = 'node.'
+      # Format of node scope : node.<access key>:<scope>
+      module Scope
+        # Node sub-scopes
+        USER = 'user:all'
+        ADMIN = 'admin:all'
+        # Separator between node.AK and user:all
+        SEPARATOR = ':'
+        NODE_PREFIX = 'node.'
+      end
       # Accepted types in `file_matcher`
       MATCH_TYPES = [String, Proc, Regexp, NilClass].freeze
       # Delimiter in decoded node token
@@ -29,20 +35,16 @@ module Aspera
       REQUIRED_APP_INFO_FIELDS = %i[api app node_info workspace_id workspace_name].freeze
       # Methods of @app_info[:api]
       REQUIRED_APP_API_METHODS = %i[node_api_from add_ts_tags].freeze
-      private_constant :SCOPE_SEPARATOR, :SCOPE_NODE_PREFIX, :MATCH_TYPES,
+      private_constant :MATCH_TYPES,
         :SIGNATURE_DELIMITER, :BEARER_TOKEN_VALIDITY_DEFAULT,
         :REQUIRED_APP_INFO_FIELDS, :REQUIRED_APP_API_METHODS
-
-      # Node API permissions
+      # Node API permissions: delete list mkdir preview read rename write
       ACCESS_LEVELS = %w[delete list mkdir preview read rename write].freeze
       # Special HTTP Headers
       HEADER_X_ASPERA_ACCESS_KEY = 'X-Aspera-AccessKey'
       HEADER_X_TOTAL_COUNT = 'X-Total-Count'
       HEADER_X_CACHE_CONTROL = 'X-Aspera-Cache-Control'
       HEADER_X_NEXT_ITER_TOKEN = 'X-Aspera-Next-Iteration-Token'
-      # Node sub-scopes
-      SCOPE_USER = 'user:all'
-      SCOPE_ADMIN = 'admin:all'
       # / in cloud
       PATH_SEPARATOR = '/'
 
@@ -63,7 +65,7 @@ module Aspera
         # Adds cache control header, as globally specified to read request
         # Use like this: read(...,**cache_control)
         def cache_control
-          headers = {'Accept' => Rest::MIME_JSON}
+          headers = {'Accept' => Mime::JSON}
           headers[HEADER_X_CACHE_CONTROL] = 'no-cache' unless use_node_cache
           {headers: headers}
         end
@@ -126,16 +128,16 @@ module Aspera
         # Node API scopes
         # @return [String] node scope
         def token_scope(access_key, scope)
-          return [SCOPE_NODE_PREFIX, access_key, SCOPE_SEPARATOR, scope].join('')
+          return [Scope::NODE_PREFIX, access_key, Scope::SEPARATOR, scope].join('')
         end
 
         # Decode node scope into access key and scope
         # @return [Hash]
         def decode_scope(scope)
-          items = scope.split(SCOPE_SEPARATOR, 2)
+          items = scope.split(Scope::SEPARATOR, 2)
           Aspera.assert(items.length.eql?(2)){"invalid scope: #{scope}"}
-          Aspera.assert(items[0].start_with?(SCOPE_NODE_PREFIX)){"invalid scope: #{scope}"}
-          return {access_key: items[0][SCOPE_NODE_PREFIX.length..-1], scope: items[1]}
+          Aspera.assert(items[0].start_with?(Scope::NODE_PREFIX)){"invalid scope: #{scope}"}
+          return {access_key: items[0][Scope::NODE_PREFIX.length..-1], scope: items[1]}
         end
 
         # Create an Aspera Node bearer token
@@ -151,7 +153,7 @@ module Aspera
           # Manage convenience parameters
           expiration_sec = payload['_validity'] || BEARER_TOKEN_VALIDITY_DEFAULT
           payload.delete('_validity')
-          scope = payload['_scope'] || SCOPE_USER
+          scope = payload['_scope'] || Scope::USER
           payload.delete('_scope')
           payload['scope'] ||= token_scope(access_key, scope)
           payload['auth_type'] ||= 'access_key'
@@ -306,7 +308,9 @@ module Aspera
       # @param top_file_id [String] id initial file id
       # @param path [String] file or folder path (end with "/" is like setting process_last_link)
       # @param process_last_link [Boolean] if true, follow the last link
-      # @return [Hash] {.api,.file_id}
+      # @return [Hash] Result data
+      # @option return [Aspera::Rest] :api     REST client instance
+      # @option return [String]       :file_id File identifier
       def resolve_api_fid(top_file_id, path, process_last_link = false)
         Aspera.assert_type(top_file_id, String)
         Aspera.assert_type(path, String)