Merge branch 'docs/GLOB-13678' into 'develop'

Prepare package for CRAN submission

See merge request r-stack/sevenbridges2!94

DESCRIPTION

@@ -1,14 +1,14 @@
 Package: sevenbridges2
 Type: Package
 Title: The 'Seven Bridges Platform' API Client
-Version: 0.1.0
+Version: 0.2.0
 Authors@R: c(
-    person("Marija", "Gacic", email = "marija.jovanovic@velsera.com", role = c("aut", "cre")),
-    person("Marko", "Trifunovic", email = "marko.trifunovic@sevenbridges.com", role = c("aut")),
+    person("Marko", "Trifunovic", email = "marko.trifunovic@velsera.com", role = c("aut", "cre")),
+    person("Marija", "Gacic", email = "marija.jovanovic@velsera.com", role = c("aut")),
     person("Vladimir", "Obucina", email = "[email protected]", role = c("aut")),
     person("Velsera", role = c("cph", "fnd"))
     )
-Maintainer: Marija Gacic <marija.jovanovic@velsera.com>
+Maintainer: Marko Trifunovic <marko.trifunovic@velsera.com>
 Description: R client and utilities for 'Seven Bridges Platform' API, from 'Cancer Genomics Cloud' 
     to other 'Seven Bridges' supported platforms. API documentation is hosted publicly 
     at <https://docs.sevenbridges.com/docs/the-api>.
@@ -48,4 +48,5 @@ Suggests:
 Config/testthat/edition: 3
 Config/testthat/parallel: true
 Roxygen: list(markdown = TRUE)
+Language: en-US
 BugReports: https://github.com/sbg/sevenbridges2/issues

NEWS.md

@@ -1,3 +1,27 @@
 # sevenbridges2 0.1.0
 
 * Initial CRAN submission.
+
+# sevenbridges2 0.2.0
+
+## Breaking changes
+
+* The package now includes support for another category of API calls: bulk actions.
+* Bulk actions allow users to perform actions on multiple items with a single call. The following bulk API methods have been added:
+  - `bulk_submit_import()` in the `Auth$imports` path allows you to import multiple volume files or folders into a project using a single API call.
+  - `bulk_get()` in the `Auth$imports` path retrieves details about a bulk import job.
+  - `bulk_submit_export()` in the `Auth$exports` path enables you to export multiple project files into a volume using a single API call.
+  - `bulk_get()` in the `Auth$exports` path fetches details about a bulk export job.
+  - `bulk_get()` in the `Auth$files` path retrieves details of multiple specified files, including file names and metadata.
+  - `bulk_update()` in the `Auth$files` path updates the details for multiple specified files, replacing existing information and clearing omitted parameters.
+  - `bulk_edit()` in the `Auth$files` path modifies existing information or adds new information for multiple specified files, while preserving omitted parameters.
+  - `bulk_delete()` in the `Auth$files` path deletes multiple specified files in a single API call.
+  - `bulk_get()` in the `Auth$tasks` path retrieves details of multiple tasks in a single API call.
+* Additionally, the package includes two utility functions: `prepare_items_for_bulk_import()` and `prepare_items_for_bulk_export()`. These functions are designed to facilitate the creation of item lists for bulk import and export operations.
+
+
+## Enhancements and fixes
+
+* Fix error handling checkers in the core `api()` function to ensure compatibility with newer versions of R. The `setequal()` function has been replaced with the custom `list_eq()` function.
+* Fix logic for setting API request header when using Seven Bridges single sign-on token for authentication.
+* Set the default value of the `fields` parameter in the core `api()` function to "_all", ensuring that all available fields are included in the API response for each resource.

R/class-apps.R

@@ -57,7 +57,7 @@ Apps <- R6::R6Class(
     #'  This is a pagination-specific attribute.
     #' @param fields Selector specifying a subset of fields to include in the
     #'  response. For querying apps it is set to return all fields except 'raw'
-    #'  which stores CWL in form of a list. Please, be careful when setting to
+    #'  which stores CWL in form of a list. Please be careful when setting to
     #'  return all fields, since the execution of this API request could be
     #'  time-consuming.
     #' @param ... Other arguments that can be passed to core `api()` function.

R/class-collection.R

@@ -198,7 +198,7 @@ Collection <- R6::R6Class(
 
     # Get all results ---------------------------------------------------------
     #' @description Fetches all available items by iterating through all pages.
-    #'  Please, be aware of the API rate limit for your request.
+    #'  Please be aware of the API rate limit for your request.
     #'
     #' @param ... Other arguments that can be passed to core `api()` function
     #'  like 'advanced_access', 'fields', etc.

R/class-exports-utils.R

@@ -30,19 +30,19 @@
 #'  }
 #'
 #' @param files A list of \code{\link{File}} objects or list of strings
-#'  (IDs) of the files you are about to export to a volume..
+#'  (IDs) of the files you are about to export to a volume.
 #' @param destination_volume Either a \code{\link{Volume}} object or the ID of
 #'  the volume to which the file will be exported.
 #' @param destination_location_prefix Character. If the volume has been
-#'  configured with a prefix parameter, `destination_location_prefix` value
-#'  will be prepended to location before attempting to create the file on the
-#'  volume. This parameter can be treated as a path to a new file on the
-#'  volume. The default value is `NULL`.
+#'  configured with a prefix parameter, \cr
+#'  `destination_location_prefix` value will be prepended to location before
+#'  attempting to create the file on the volume. This parameter can be treated
+#'  as a path to a new file on the volume. The default value is `NULL`.
 #'
-#'  If you would like to export the file into some folder on the volume,
-#'  please add folder name as prefix before file name in form
-#'  `<folder-name>/`. Remember to put a slash character at the end of a
-#'  string.
+#'  If you would like to export the file into a folder on the volume,
+#'  please add folder name as the prefix before the file name in the
+#'  `"<folder-name>/"` form. Remember to put a slash character ("/") at the end
+#'  of the string.
 #'
 #'  Keep in mind that the same prefix will be added to all items (files) in the
 #'  resulting list.
@@ -63,15 +63,15 @@
 #'      KMS key. If not set and `aws:kms` is set as `sse_algorithm`,
 #'      default KMS key is used.
 #'    \item `aws_canned_acl`: S3 canned ACL to apply on the object
-#'      on during export. Supported values: any one of
+#'      during export. Supported values: any one of
 # nolint start
 #'      [S3 canned ACLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl);
 # nolint end
 #'      `null` (do not apply canned ACLs). Default: `null`.
 #'  }
 #'
-#'  Keep in mind that the same properties options will be applied to all items
-#'  (files) in the resulting list.
+#'  Keep in mind that the same properties will be applied to all items (files)
+#'  in the resulting list.
 #'
 #' @seealso \code{\link{Exports}}, \code{\link{File}}, \code{\link{Volume}}
 #'
@@ -123,7 +123,7 @@ prepare_items_for_bulk_export <- function(files, destination_volume, destination
   for (file in files) {
     if (checkmate::test_r6(file, classes = "File") &&
       tolower(file$type) == "folder") {
-      rlang::abort("Provided list contains folder objects which cannot be exported. Please make sure to remove all folder objects (type = 'folder') and try again.") # nolint
+      rlang::abort("Provided list contains folder objects, which cannot be exported. Please make sure to remove all folder objects (type = 'folder') and try again.") # nolint
     }
   }
 

R/class-exports.R

@@ -226,7 +226,7 @@ Exports <- R6::R6Class(
       }
       if (checkmate::test_r6(source_file, classes = "File") &&
         tolower(source_file$type) == "folder") {
-        rlang::abort("Folders cannot be exported. Please, provide single file id or File object with type = 'file'.") # nolint
+        rlang::abort("Folders cannot be exported. Please provide a single file ID or File object with type = 'file'.") # nolint
       }
       file <- check_and_transform_id(source_file, class_name = "File")
 
@@ -316,7 +316,7 @@ Exports <- R6::R6Class(
     #'  objects.
     bulk_get = function(exports) {
       if (is_missing(exports)) {
-        rlang::abort("Exports should be set as list of export job IDs or as list of Export objects.") # nolint
+        rlang::abort("Exports should be set as a list of export job IDs or list of Export objects.") # nolint
       }
 
       checkmate::assert_list(exports)
@@ -360,32 +360,31 @@ Exports <- R6::R6Class(
     #'  storage price on the Platform. In summary, once you export files from
     #'  the Platform to a volume, they are no longer part of the storage on
     #'  the Platform and cannot be exported again.
+    #'
     # nolint start
     #'  Learn more about using the Volumes API for [Amazon S3](https://docs.sevenbridges.com/docs/aws-cloud-storage-tutorial) and
     #'  for [Google Cloud Storage](https://docs.sevenbridges.com/docs/google-cloud-storage-tutorial).
     # nolint end
     #'
     #' @param items Nested list of elements containing information about each
     #'  file to be exported. For each element, users must provide:
-    #'
-    # nolint start
     #'  \itemize{
-    #'      \item `source_file` - File id or File object you want to export to
+    #'      \item `source_file` - File ID or File object you want to export to
     #'        the volume,
-    #'      \item `destination_volume` - Volume id or Volume object you want to
+    #'      \item `destination_volume` - Volume ID or Volume object you want to
     #'        export files into.
     #'      \item `destination_location` - Volume-specific location to which
     #'        the file will be exported. This location should be recognizable
     #'        to the underlying cloud service as a valid key or path to a
     #'        new file. Please note that if this volume has been configured
-    #'        with a `prefix` parameter, the value of `prefix` will be prepended
-    #'        to location before attempting to create the file on the volume.
-    #'
-    #'        If you would like to export the file into some folder on the
-    #'        volume, please add folder name as prefix before file name
-    #'        in form `<folder-name>/<file-name>`.
+    #'        with a `prefix` parameter, the value of `prefix` will be
+    #'        prepended to the location before attempting to create the file on
+    #'        the volume. \cr
+    #'        If you would like to export the file into a folder on
+    #'        the volume, please add folder name as a prefix before the file
+    #'        name in the `<folder-name>/<file-name>` form.
     #'      \item `overwrite` - Set to `TRUE` if you want to overwrite the
-    #'        item if another one with the same name already exists at the
+    #'        item with the same name if it already exists at the
     #'        destination.
     #'      \item `properties` - Named list of additional volume properties,
     #'        like:
@@ -399,12 +398,15 @@ Exports <- R6::R6Class(
     #'            required KMS key. If not set and `aws:kms` is set as
     #'            `sse_algorithm`, default KMS key is used.
     #'          \item `aws_canned_acl`: S3 canned ACL to apply on the object
-    #'            on during export. Supported values: any one of
+    #'            during export. Supported values: any one of
+    # nolint start
     #'      [S3 canned ACLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl);
     #'      `null` (do not apply canned ACLs). Default: `null`.
     #'      }
     #'  }
     # nolint end
+    #'
+    #'
     #'  Example of the list:
     #'  ```{r}
     #'  items <- list(
@@ -429,13 +431,14 @@ Exports <- R6::R6Class(
     #'            )
     #'          )
     #' ```
-    #'  More details of how to export files from your project into the volume
+    #'
     # nolint start
-    #'  or some volume's folder you can read [here](https://docs.sevenbridges.com/reference/start-a-bulk-export-job)
+    #'  Read more on how to [export files from your project to a volume or a volume folder](https://docs.sevenbridges.com/reference/start-a-bulk-export-job).
     # nolint end
     #'
     #'  Utility function \code{\link{prepare_items_for_bulk_export}} can help
-    #'  you to prepare the `items` parameter for `bulk_submit_export()` method.
+    #'  you prepare the `items` parameter for the `bulk_submit_export()`
+    #'  method.
     #'
     #' @param copy_only If set to true, the files will be copied to a volume
     #'  but the source files will remain on the Platform.
@@ -479,7 +482,7 @@ Exports <- R6::R6Class(
     #'  objects.
     bulk_submit_export = function(items, copy_only = FALSE) {
       if (is_missing(items)) {
-        rlang::abort("Items parameter should be set as nested list of files information you want to export.") # nolint
+        rlang::abort("Items parameter should be set as a nested list of information on files you want to export.") # nolint
       }
       checkmate::assert_list(items)
 
@@ -498,7 +501,7 @@ Exports <- R6::R6Class(
         }
         if (checkmate::test_r6(item[["source_file"]], classes = "File") &&
           tolower(item[["source_file"]]$type) == "folder") {
-          rlang::abort(glue::glue("Folders cannot be exported. Please, provide single file id or File object with type = 'file' in element {i}.")) # nolint
+          rlang::abort(glue::glue("Folders cannot be exported. Please provide a single file ID or File object with type = 'file' in element {i}.")) # nolint
         }
         body_element$source <- list(
           file = check_and_transform_id(item[["source_file"]],
@@ -560,15 +563,15 @@ Exports <- R6::R6Class(
       }
 
       if (length(failed_export_tries) == length(res$items)) {
-        rlang::abort("All files cannot to be exported. Please, check the limitations of files export in the API documentation.") # nolint
+        rlang::abort("None of the files can be exported. Please check file export limitations in the API documentation.") # nolint
       }
 
       res$items <- asExportList(res, auth = self$auth, bulk = TRUE)
-      rlang::inform(glue::glue("New export jobs have started!"))
+      rlang::inform(glue::glue("New export jobs have started."))
 
       if (length(failed_export_tries) > 0) {
         rlang::inform(glue::glue("However, some files cannot be exported.
-                                 Please, check the limitations of files export in the API documentation.")) # nolint
+                                 Please check file export limitations in the API documentation.")) # nolint
       }
 
       return(asCollection(res, auth = self$auth))

R/class-file.R

@@ -769,7 +769,7 @@ File <- R6::R6Class(
       }
 
       if (is_missing(directory_path)) {
-        rlang::abort("Please, provide directory path where to download your file.") # nolint
+        rlang::abort("Please provide directory path where to download your file.") # nolint
       } else {
         # check if directory exists
         check_download_path(directory_path, filename)

R/class-files.R

@@ -394,18 +394,18 @@ Files <- R6::R6Class(
     #' @examples
     #' \dontrun{
     #'  # Delete two files by providing their IDs
-    #'  a$files$delete(files = list("file_1_ID", "file_2_ID"))
+    #'  a$files$bulk_delete(files = list("file_1_ID", "file_2_ID"))
     #' }
     #'
     #' \dontrun{
     #'  # Delete two files by providing a list of File objects
-    #'  a$files$delete(files = list(File_Object_1, File_Object_2))
+    #'  a$files$bulk_delete(files = list(File_Object_1, File_Object_2))
     #' }
     #'
     bulk_delete = function(files) {
       if (is_missing(files)) {
         rlang::abort(
-          "Please provide 'files' parameter."
+          "Please provide the 'files' parameter."
         )
       }
 
@@ -455,7 +455,7 @@ Files <- R6::R6Class(
     bulk_get = function(files) {
       if (is_missing(files)) {
         rlang::abort(
-          "Please provide 'files' parameter."
+          "Please provide the 'files' parameter."
         )
       }
 
@@ -487,7 +487,7 @@ Files <- R6::R6Class(
     #'  replacing all existing information and erasing omitted parameters.
     #'
     #' @details For each of the specified files, the call sets a new `name`,
-    #'  new `tags` and `metadata`.
+    #'  new `tags`, and `metadata`.
     #'
     #'  When editing fields in the \code{\link{File}} objects you wish to
     #'   update, keep the following in mind:
@@ -525,7 +525,7 @@ Files <- R6::R6Class(
     bulk_update = function(files) {
       if (is_missing(files)) {
         rlang::abort(
-          "Please provide 'files' parameter."
+          "Please provide the 'files' parameter."
         )
       }
 
@@ -546,7 +546,7 @@ Files <- R6::R6Class(
         body = body
       )
 
-      rlang::inform(cli::cli_text("{cli::qty(length(files))} File{?s} {?has/have} been updated!")) # nolint
+      rlang::inform(cli::cli_text("{cli::qty(length(files))} File{?s} {?has/have} been updated.")) # nolint
 
       res$items <- asFileList(res, auth = self$auth, bulk = TRUE)
 
@@ -557,10 +557,10 @@ Files <- R6::R6Class(
     # Edit details of multiple files
     #'
     #' @description This method modifies the existing information for specified
-    #'  files or add new information while preserving omitted parameters.
+    #'  files or adds new information while preserving omitted parameters.
     #'
     #' @details For each of the specified files, the call edits its `name`,
-    #'  `tags` and `metadata`.
+    #'  `tags`, and `metadata`.
     #'
     #'  When editing fields in the \code{\link{File}} objects you wish to
     #'  update, keep the following in mind:
@@ -598,7 +598,7 @@ Files <- R6::R6Class(
     bulk_edit = function(files) {
       if (is_missing(files)) {
         rlang::abort(
-          "Please provide 'files' parameter."
+          "Please provide the 'files' parameter."
         )
       }
 
@@ -619,7 +619,7 @@ Files <- R6::R6Class(
         body = body
       )
 
-      rlang::inform(cli::cli_text("{cli::qty(length(files))} File{?s} {?has/have} been updated!")) # nolint
+      rlang::inform(cli::cli_text("{cli::qty(length(files))} File{?s} {?has/have} been updated.")) # nolint
 
       res$items <- asFileList(res, auth = self$auth, bulk = TRUE)