aspera-cli 4.25.1 → 4.25.3

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

@@ -102,7 +102,7 @@ module Aspera
           # @param destination_folder [String] Base folder
           # @param fld.               [Array]  List of fields of package
           def unique_folder(package_info, destination_folder, fld: nil, seq: false, opt: false)
-            Aspera.assert_array_all(fld, String, type: Cli::BadArgument){'fld'}
+            Aspera.assert_array_all(fld, String, type: BadArgument){'fld'}
             Aspera.assert([1, 2].include?(fld.length)){'fld must have 1 or 2 elements'}
             folder = Environment.instance.sanitized_filename(package_info[fld[0]])
             if seq
@@ -181,7 +181,7 @@ module Aspera
           end
           myself = aoc_api.read('self')
           if auto_set_pub_key
-            Aspera.assert(myself['public_key'].empty?, type: Cli::Error){'Public key is already set in profile (use --override=yes)'} unless option_override
+            Aspera.assert(myself['public_key'].empty?, type: 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
@@ -224,21 +224,18 @@ module Aspera
           @scope = new_scope
         end
 
-        # create an API object with the same options, but with a different subpath
+        # Create an API object with the options from CLI, but with a different subpath
         # @param aoc_base_path [String] New subpath
         # @return [Api::AoC] API object for AoC (is Rest)
         def api_from_options(aoc_base_path)
-          return new_with_options(
-            Api::AoC,
-            kwargs: {
-              scope:         @scope,
-              subpath:       aoc_base_path,
-              secret_finder: config
-            },
-            option: {
-              workspace: nil
-            }
-          )
+          return Api::AoC.new(**Oauth.args_from_options(
+            options,
+            defaults:      {workspace: nil},
+            scope:         @scope,
+            subpath:       aoc_base_path,
+            secret_finder: config,
+            progress_disp: formatter
+          ))
         end
 
         # AoC Rest object
@@ -256,11 +253,11 @@ module Aspera
         end
 
         # Generate or update Hash with workspace id and name (option), if not already set
-        # @param hash   [Hash,nil] Optional base hash (modified)
-        # @param string [Boolean] true to set key as string, else as symbol
-        # @param name   [Boolean] include name
+        # @param hash   [Hash,nil] Optional base `Hash` (modified)
+        # @param string [Boolean] `true` to set key as `String`, else as `Symbol`
+        # @param name   [Boolean] 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)
+        def workspace_id_hash(hash = nil, string: false, name: false)
           info = aoc_api.workspace
           hash = {} if hash.nil?
           fields = %i[id]
@@ -273,12 +270,12 @@ module Aspera
           return hash
         end
 
-        # Get resource identifier from command line, either directly or from name.
+        # Get resource identifier from command line, either directly specifying the `id` or from `name` (percent selector).
         # @param resource_class_path url path for resource
         # @return identifier
         def get_resource_id_from_args(resource_class_path)
           return instance_identifier do |field, value|
-            Aspera.assert(field.eql?('name'), type: Cli::BadArgument){'only selection by name is supported'}
+            Aspera.assert(field.eql?('name'), type: BadArgument){'only selection by name is supported'}
             aoc_api.lookup_by_name(resource_class_path, value)['id']
           end
         end
@@ -300,7 +297,7 @@ module Aspera
           query = query_read_delete(default: default_query)
           # caller may add specific modifications or checks to query
           yield(query) if block_given?
-          result = aoc_api.read_with_paging(resource_class_path, base_query.merge(query).compact, formatter: formatter)
+          result = aoc_api.read_with_paging(resource_class_path, base_query.merge(query).compact)
           return Main.result_object_list(result[:items], fields: fields, total: result[:total])
         end
 
@@ -312,7 +309,7 @@ module Aspera
             # 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
-          workspace_id_hash(hash: query, string: true)
+          workspace_id_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
@@ -325,7 +322,7 @@ module Aspera
           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 aoc_api.read_with_paging('packages', query.compact, formatter: formatter)
+          return aoc_api.read_with_paging('packages', query.compact)
         end
 
         NODE4_EXT_COMMANDS = %i[transfer].concat(Node::COMMANDS_GEN4).freeze
@@ -470,11 +467,11 @@ module Aspera
             return Main.result_success
           when :do
             command_repo = options.get_next_command(NODE4_EXT_COMMANDS)
-            return execute_nodegen4_command(command_repo, res_id, scope: Api::Node::SCOPE_ADMIN)
+            return execute_nodegen4_command(command_repo, res_id, scope: Api::Node::Scope::ADMIN)
           when :bearer_token
             node_api = aoc_api.node_api_from(
               node_id: res_id,
-              scope:   options.get_next_argument('scope')
+              scope:   options.get_next_argument('scope', default: Api::Node::Scope::ADMIN)
             )
             return Main.result_text(node_api.oauth.authorization)
           when :dropbox
@@ -504,7 +501,7 @@ module Aspera
                   node_id: shared_folder['node_id'],
                   workspace_id: res_id,
                   workspace_name: nil,
-                  scope: Api::Node::SCOPE_USER
+                  scope: Api::Node::Scope::USER
                 )
                 result = node_api.read(
                   'permissions',
@@ -741,110 +738,132 @@ module Aspera
           end
         end
 
-        # Create a shared link for the given entity
-        # @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 Aspera.error_unexpected_value(purpose_public){'public link purpose'}
-            end
-          when :private then 'shared_folder_auth_link'
-          else Aspera.error_unreachable_line
+        # Create a short link for the given entity: Shared folder or Shared Inbox
+        # Short link entity: `short_links` have:
+        # - a numerical id, e.g. `764412`
+        # - a resource type, e.g. `UrlToken`
+        # - a ressource id, e.g. `scQ7uXPbvQ`
+        # - a short URL path, e.g. `dxyRpT9`
+        # @param shared_data [Hash] Information for shared data: dropbox_id+name or file_id+node_id
+        # @param &perm_block [Proc] Optional: create/modify/delete permissions on node
+        def short_link_command(**shared_data, &perm_block)
+          link_type = options.get_next_argument('link access (public or private)', accept_list: %i[public private])
+          if shared_data.keys.sort == %i[dropbox_id name]
+            # Packages app, Shared inbox
+            token_purpose = 'send_package_to_dropbox'
+            short_link_purpose = link_type.eql?(:public) ? 'send_package_to_dropbox' : 'shared_folder_auth_link'
+          elsif shared_data.keys.sort == %i[file_id node_id]
+            # Files app, Shared folder
+            token_purpose = 'view_shared_file'
+            short_link_purpose = link_type.eql?(:public) ? 'token_auth_redirection' : 'shared_folder_auth_link'
+          else
+            Aspera.error_unexpected_value(shared_data.keys)
           end
-          command = options.get_next_command(%i[create delete list show modify])
+          command = options.get_next_command(%i[create delete list show] + (link_type.eql?(:public) ? %i[modify] : []))
           case command
           when :create
-            entity_data = {
-              purpose:            purpose_local,
+            # Add workspace id
+            workspace_id_hash(shared_data)
+            create_payload = {
+              purpose:            short_link_purpose,
               user_selected_name: nil
             }
             case link_type
             when :private
-              entity_data[:data] = shared_data
+              create_payload[:data] = shared_data
             when :public
-              entity_data[:expires_at]       = nil
-              entity_data[:password_enabled] = false
+              create_payload[:expires_at]       = nil
+              create_payload[:password_enabled] = false
               shared_data[:name] = ''
-              entity_data[:data] = {
+              create_payload[:data] = {
                 aoc:            true,
                 url_token_data: {
                   data:    shared_data,
-                  purpose: purpose_public
+                  purpose: token_purpose
                 }
               }
             end
             custom_data = value_create_modify(command: command, default: {})
+            access_levels = custom_data.delete('access_levels')
             if (pass = custom_data.delete('password'))
-              entity_data[:data][:url_token_data][:password] = pass
-              entity_data[:password_enabled] = true
+              create_payload[:data][:url_token_data][:password] = pass
+              create_payload[: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)
+            create_payload.deep_merge!(custom_data)
+            result_create_short_link = aoc_api.create('short_links', create_payload)
+            # Creation: perm_block: permission on node
+            yield(:create, result_create_short_link['resource_id'], access_levels) if block_given? && link_type.eql?(:public)
             return Main.result_single_object(result_create_short_link)
-          when :list, :show
+          when :delete, :list, :show, :modify
+            workspace_id_hash(shared_data)
             query = if link_type.eql?(:private)
               shared_data
             else
               {
                 url_token_data: {
                   data:    shared_data,
-                  purpose: purpose_public
+                  purpose: token_purpose
                 }
               }
             end
             list_params = {
               json_query:  query.to_json,
-              purpose:     purpose_local,
+              purpose:     short_link_purpose,
               edit_access: true,
               # embed: 'updated_by_user',
               sort:        '-created_at'
             }
-            return result_list('short_links', fields: Formatter.all_but('data'), base_query: list_params) if command.eql?(:list)
-            one_id = instance_identifier
-            found = aoc_api.read_with_paging('short_links', list_params, formatter: formatter)[: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
+            short_list = aoc_api.read_with_paging('short_links', list_params.merge(query_read_delete(default: {})).compact)
+            case command
+            when :delete
+              one_id = instance_identifier(description: 'short link id')
+              if link_type.eql?(:public)
+                found = short_list[:items].find{ |item| item['id'].eql?(one_id)}
+                raise BadIdentifier.new('Short link', one_id) if found.nil?
+                yield(:delete, found['resource_id'], nil)
+              end
+              aoc_api.delete("short_links/#{one_id}", {
+                edit_access: true,
+                json_query:  shared_data.to_json
+              })
+              return Main.result_status('deleted')
+            when :list
+              return Main.result_object_list(short_list[:items], fields: Formatter.all_but('data'), total: short_list[:total])
+            when :show
+              one_id = instance_identifier(description: 'short link id')
+              found = short_list[:items].find{ |item| item['id'].eql?(one_id)}
+              raise BadIdentifier.new('Short link', one_id) if found.nil?
+              return Main.result_single_object(found, fields: Formatter.all_but('data'))
+            when :modify
+              one_id = instance_identifier(description: 'short link id')
+              node_file = shared_data.slice(:node_id, :file_id)
+              modify_payload = {
+                edit_access: true,
+                json_query:  node_file
+              }
+              custom_data = value_create_modify(command: command)
+              if (pass = custom_data.delete('password'))
+                modify_payload[:password_enabled] = true
+                modify_payload[:data] = {
+                  url_token_data: {
+                    password: pass,
+                    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)
-            delete_params = {
-              edit_access: true,
-              json_query:  shared_data.to_json
-            }
-            aoc_api.delete("short_links/#{one_id}", delete_params)
-            if link_type.eql?(:public)
-              # TODO: get permission id..
-              # shared_apfid[:api].delete('permissions', {ids: })
+              else
+                modify_payload[:password_enabled] = false
+              end
+              if custom_data.delete('access_levels')
+                # Modification: perm_block: permission on node
+                found = short_list[:items].find{ |item| item['id'].eql?(one_id)}
+                raise BadIdentifier.new('Short link', one_id) if found.nil?
+                yield(:update, found['resource_id'], access_levels)
+              end
+              modify_payload.deep_merge!(custom_data)
+              aoc_api.update("short_links/#{one_id}", modify_payload)
+              return Main.result_status('modified')
             end
-            return Main.result_status('deleted')
+          else Aspera.error_unexpected_value(command)
           end
         end
 
@@ -935,24 +954,20 @@ 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'}
-                workspace_id_hash(hash: default_query, string: true)
+                workspace_id_hash(default_query, string: true)
                 return result_list('dropbox_memberships', fields: %w[dropbox_id dropbox.name], default_query: default_query)
               when :show
                 return Main.result_single_object(aoc_api.read(get_resource_path_from_args('dropboxes')))
               when :short_link
-                return short_link_command(
-                  purpose_public: 'send_package_to_dropbox',
-                  dropbox_id:     get_resource_id_from_args('dropboxes'),
-                  name:           '',
-                  **workspace_id_hash
-                )
+                # TODO: check name
+                return short_link_command(dropbox_id: get_resource_id_from_args('dropboxes'), name: '')
               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 user auth and link auth.
-              workspace_id_hash(hash: package_data, string: true) unless package_data.key?('workspace_id')
+              workspace_id_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
@@ -1041,7 +1056,7 @@ module Aspera
               return Main.result_object_list(result[:items], fields: display_fields, total: result[:total])
             when :delete
               return do_bulk_operation(command: package_command, values: instance_identifier) do |id|
-                Aspera.assert_values(id.class, [String, Integer]){'identifier'}
+                Aspera.assert_type(id, String, Integer){'identifier'}
                 aoc_api.delete("packages/#{id}")
               end
             when :modify
@@ -1052,13 +1067,13 @@ module Aspera
             when *Node::NODE4_READ_ACTIONS
               package_id = instance_identifier
               package_info = aoc_api.read("packages/#{package_id}")
-              return execute_nodegen4_command(package_command, package_info['node_id'], file_id: package_info['contents_file_id'], scope: Api::Node::SCOPE_USER)
+              return execute_nodegen4_command(package_command, package_info['node_id'], file_id: package_info['contents_file_id'], scope: Api::Node::Scope::USER)
             end
           when :files
             command_repo = options.get_next_command([:short_link].concat(NODE4_EXT_COMMANDS))
             case command_repo
             when *NODE4_EXT_COMMANDS
-              return execute_nodegen4_command(command_repo, aoc_api.home[:node_id], file_id: aoc_api.home[:file_id], scope: Api::Node::SCOPE_USER)
+              return execute_nodegen4_command(command_repo, aoc_api.home[:node_id], file_id: aoc_api.home[:file_id], scope: Api::Node::Scope::USER)
             when :short_link
               folder_dest = options.get_next_argument('path', validation: String)
               home_node_api = aoc_api.node_api_from(
@@ -1067,33 +1082,42 @@ module Aspera
               )
               shared_apfid = home_node_api.resolve_api_fid(aoc_api.home[:file_id], folder_dest)
               return short_link_command(
-                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']
-                       perm_data = {
-                         'file_id'       => shared_apfid[:file_id],
-                         'access_id'     => resource_id,
-                         'access_type'   => 'user',
-                         'access_levels' => access_levels,
-                         'tags'          => {
-                           # TODO: really just here ? not in tags.aspera.files.workspace ?
-                           'url_token'        => true,
-                           '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'],
-                           **workspace_id_hash(string: true, name: true)
-                         }
-                       }
-                       created_data = shared_apfid[:api].create('permissions', perm_data)
-                       aoc_api.permissions_send_event(event_data: created_data, app_info: shared_apfid[:api].app_info)
-                     end
+                file_id:        shared_apfid[:file_id]
+              ) do |op, id, access_levels|
+                case op
+                when :create
+                  # `id` is the resource id
+                  perm_data = {
+                    'file_id'       => shared_apfid[:file_id],
+                    'access_id'     => id,
+                    'access_type'   => 'user',
+                    'access_levels' => Api::AoC.expand_access_levels(access_levels),
+                    'tags'          => {
+                      'url_token'        => true,
+                      '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]['name'],
+                      **workspace_id_hash(string: true, name: true)
+                    }
+                  }
+                  created_data = shared_apfid[:api].create('permissions', perm_data)
+                  aoc_api.permissions_send_event(event_data: created_data, app_info: shared_apfid[:api].app_info)
+                when :update
+                  # `id` is the permission_id
+                  found = shared_apfid[:api].read('permissions', {file_id: shared_apfid[:file_id], inherited: false, access_type: 'user', access_id: id}).find{ |i| i['access_id'].eql?(id)}
+                  raise Error, 'Short link not found: #{id}' if found.nil?
+                  shared_apfid[:api].update("permissions/#{found['id']}", {access_levels: Api::AoC.expand_access_levels(access_levels)})
+                when :delete
+                  # `id` is the resource id, i.e. `access_id`
+                  found = shared_apfid[:api].read('permissions', {file_id: shared_apfid[:file_id], inherited: false, access_type: 'user', access_id: id}).first
+                  raise Error, 'Short link not found: #{id}' if found.nil?
+                  shared_apfid[:api].delete("permissions/#{found['id']}")
+                else Aspera.error_unexpected_value(op)
+                end
+              end
             end
           when :automation
             change_api_scope(Api::AoC::Scope::ADMIN_USER)

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

@@ -22,7 +22,6 @@ module Aspera
         class << self
           def declare_options(options)
             options.declare(:query, 'Additional filter for for some commands (list/delete)', allowed: [Hash, Array, NilClass])
-            options.declare(:property, 'Name of property to set (modify operation)')
             options.declare(:bulk, 'Bulk operation (only some)', allowed: Allowed::TYPES_BOOLEAN, default: false)
             options.declare(:bfail, 'Bulk operation error handling', allowed: Allowed::TYPES_BOOLEAN, default: true)
           end
@@ -40,7 +39,7 @@ module Aspera
         def initialize(context:)
           # Check presence in descendant of mandatory method and constant
           Aspera.assert(respond_to?(:execute_action), type: InternalError){"Missing method 'execute_action' in #{self.class}"}
-          Aspera.assert(self.class.constants.include?(:ACTIONS), type: InternalError){"Missing constant 'ACTIONS' in #{self.class}"}
+          Aspera.assert(self.class.const_defined?(:ACTIONS), type: InternalError){"Missing constant 'ACTIONS' in #{self.class}"}
           @context = context
           add_manual_header if @context.man_header
         end
@@ -70,25 +69,25 @@ module Aspera
         # Resource identifier as positional parameter
         #
         # @param description [String] description of the identifier
-        # @param block       [Proc] block to search for identifier based on attribute value
+        # @param &block      [Proc] block to search for identifier based on attribute value
         # @return   [String, Array] identifier or list of ids
-        def instance_identifier(description: 'identifier', &block)
+        def instance_identifier(description: 'identifier')
           res_id = options.get_next_argument(description, multiple: options.get_option(:bulk)) if res_id.nil?
           # Can be an Array
           if res_id.is_a?(String) && (m = Base.percent_selector(res_id))
-            Aspera.assert(block, type: Cli::BadArgument){"Percent syntax for #{description} not supported in this context"}
+            Aspera.assert(block_given?, type: Cli::BadArgument){"Percent syntax for #{description} not supported in this context"}
             res_id = yield(m[:field], m[:value])
           end
           return res_id
         end
 
         # For create and delete operations: execute one action or multiple if bulk is yes
-        # @param command   [Symbol] operation: :create, :delete, ...
-        # @param descr     [String] description of the value
-        # @param values    [Object] the value(s), or the type of value to get from user
-        # @param id_result [String] key in result hash to use as identifier
-        # @param fields    [Array]  fields to display
-        # @param &block    [Proc]   block to execute for each value
+        # @param command   [Symbol] Operation: :create, :delete, ...
+        # @param descr     [String] Description of the value
+        # @param values    [Object] Value(s), or type of value to get from user
+        # @param id_result [String] Key in result hash to use as identifier
+        # @param fields    [Array]  Fields to display
+        # @param &block    [Proc]   Block to execute for each value
         def do_bulk_operation(command:, descr: nil, values: Hash, id_result: 'id', fields: :default)
           Aspera.assert(block_given?){'missing block'}
           is_bulk = options.get_option(:bulk)
@@ -178,7 +177,7 @@ module Aspera
               api.delete(
                 entity,
                 nil,
-                content_type: Rest::MIME_JSON,
+                content_type: Mime::JSON,
                 body:         {delete_style => one_res_id}
               )
               return Main.result_status('deleted')
@@ -209,20 +208,18 @@ module Aspera
               return Main.result_object_list(data, fields: display_fields) if data.empty? || data.first.is_a?(Hash)
               return Main.result_value_list(data)
             else
-              raise "An error occurred: unexpected result type for list: #{data.class}"
+              Aspera.error_unexpected_value(data.class.name){'list type'}
             end
           when :modify
             parameters = value_create_modify(command: command)
-            property = options.get_option(:property)
-            parameters = {property => parameters} unless property.nil?
             api.update(one_res_path, parameters)
             return Main.result_status('modified')
           else
-            raise "unknown action: #{command}"
+            Aspera.error_unexpected_value(command){'command'}
           end
         end
 
-        # Query parameters in URL suitable for REST: list/GET and delete/DELETE
+        # Query parameters in URL suitable for REST: list/`GET` and delete/`DELETE`
         def query_read_delete(default: nil)
           # Dup default, as it could be frozen
           query = options.get_option(:query) || default.dup
@@ -267,7 +264,7 @@ module Aspera
         # @param entity    [String,Symbol] API endpoint of entity to list
         # @param items_key [String]        Key in the result to get the list of items (Default: same as `entity`)
         # @param query     [Hash,nil]      Additional query parameters
-        # @return [Array] items, total_count
+        # @return [Array<(Array<Hash>, Integer)>] items, total_count
         def list_entities_limit_offset_total_count(
           api:,
           entity:,