feat: add get_packages() and get_content_packages() functions (#374)

Author: toph-allen

NAMESPACE

@@ -72,6 +72,7 @@ export(filter_tag_tree_id)
 export(get_audit_logs)
 export(get_bundles)
 export(get_content)
+export(get_content_packages)
 export(get_content_permissions)
 export(get_content_tags)
 export(get_environment)
@@ -87,6 +88,7 @@ export(get_log)
 export(get_my_permission)
 export(get_oauth_content_credentials)
 export(get_oauth_credentials)
+export(get_packages)
 export(get_procs)
 export(get_runtime_caches)
 export(get_runtimes)

NEWS.md

@@ -1,5 +1,12 @@
 # connectapi (development version)
 
+## New features
+
+- New `get_packages()` function to get a data frame of all packages on a Connect
+  server. (#374)
+- New `get_content_packages()` function to get a data frame of all package
+  dependencies for a content item. (#374)
+
 # connectapi 0.6.0
 
 ## New features

R/connect.R

@@ -815,7 +815,7 @@ Connect <- R6::R6Class(
     schedules = function(start = Sys.time(), end = Sys.time() + 60 * 60 * 24 * 7, detailed = FALSE) {
       warn_experimental("schedules")
       url <- v1_url("experimental", "schedules")
-      query_params <- rlang::list2(
+      query_params <- list(
         detailed = tolower(detailed),
         start = datetime_to_rfc3339(start),
         end = datetime_to_rfc3339(end)
@@ -824,6 +824,22 @@ Connect <- R6::R6Class(
       return(res[["schedules"]])
     },
 
+    # packages --------------------------------------------------
+
+    #' @description Get packages.
+    #' @param name The package name to filter by.
+    #' @param page_number The page number.
+    #' @param page_size Page size, max 500.
+    packages = function(name = NULL, page_number = 1, page_size = 500) {
+      url <- v1_url("packages")
+      query_params <- list(
+        name = name,
+        page_number = page_number,
+        page_size = page_size
+      )
+      self$GET(url, query = query_params)
+    },
+
     # misc utilities --------------------------------------------
 
     #' @description Get documentation.

R/content.R

@@ -297,7 +297,7 @@ Content <- R6::R6Class(
         )
       )
     },
-    #' @description Adjust Git repository.
+    #' @description Adjust Git repository
     #' @param repository Git repository URL
     #' @param branch Git repository branch
     #' @param subdirectory Git repository directory
@@ -312,6 +312,10 @@ Content <- R6::R6Class(
         )
       )
     },
+    #' @description Get package dependencies
+    packages = function() {
+      self$connect$GET(v1_url("content", self$content$guid, "packages"))
+    },
     #' @description Print this object.
     #' @param ... Unused.
     print = function(...) {
@@ -1286,3 +1290,31 @@ content_restart <- function(content) {
   # nolint end
   invisible(NULL)
 }
+
+#' Package dependencies for a content item
+#'
+#' @description Get a data frame of package dependencies used by a content item.
+#'
+#' @param content A content item
+#'
+#' @return A data frame with the following columns:
+#'
+#' - `language` : Language ecosystem the package belongs to (`r` or `python`)
+#' - `name`: The package name
+#' - `version`: The package version
+#' - `hash`: For R packages, the package `DESCRIPTION` hash
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#' item <- content_item(client, "951bf3ad-82d0-4bca-bba8-9b27e35c49fa")
+#' packages <- get_content_packages(item)
+#' }
+#'
+#' @family packages functions
+#' @export
+get_content_packages <- function(content) {
+  error_if_less_than(content$connect$version, "2025.01.0")
+  res <- content$packages()
+  parse_connectapi_typed(res, connectapi_ptypes$content_packages)
+}

R/get.R

@@ -742,6 +742,72 @@ get_runtimes <- function(client, runtimes = NULL) {
   })
 }
 
+#' All package dependencies on the server
+#'
+#' @description Get a data frame of all package dependencies used by content
+#' items on the server.
+#'
+#' The `page_size` and `limit` parameters are optional but may be useful during
+#' development, when you're iterating on some code that uses this function.
+#' Behind the scenes, Connect returns packages in pages, and with large or
+#' long-running servers, this can take a while. Setting a `limit` causes
+#' Connect to stop early, giving you incomplete data, but faster.
+#'
+#' @param src A `Connect` client object.
+#' @param name Optional package name to filter by. Python package are normalized
+#' during matching; R package names must match exactly.
+#' @param page_size Optional, max 500. Integer specifying page size for API
+#' paging.
+#' @param limit Optionally specify the maximum number of records to return.
+#'
+#' @return A data frame with the following columns:
+#'
+#' - `language`: Language ecosystem the package belongs to (`r` or `python`)
+#' - `language_version`: Version of R or Python used by the content
+#' - `name`: Package name
+#' - `version`: Package version
+#' - `hash`: Package description hash for R packages
+#' - `bundle_id`: Identifier for the bundle that depends on this package
+#' - `content_id`: Numeric identifier for the content that depends on this
+#'   package
+#' - `content_guid`: The unique identifier of the content item that depends on
+#'   this package
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#' packages <- get_packages(client)
+#' }
+#'
+#' @family packages functions
+#' @export
+get_packages <- function(src, name = NULL, page_size = 500, limit = Inf) {
+  validate_R6_class(src, "Connect")
+  error_if_less_than(src$version, "2024.11.0")
+  res <- page_offset(
+    src,
+    src$packages(
+      name = name,
+      page_size = page_size
+    ),
+    limit = limit
+  )
+  out <- parse_connectapi_typed(res, connectapi_ptypes$packages)
+
+  # Connect is standardizing on using `content_id` and `content_guid`.
+  # Handle that name change now in a forward-compatible way.
+  if ("app_id" %in% names(out)) {
+    out$content_id <- out$app_id
+    out$app_id <- NULL
+  }
+  if ("app_guid" %in% names(out)) {
+    out$content_guid <- out$app_guid
+    out$app_guid <- NULL
+  }
+
+  out
+}
+
 #' Get all vanity URLs
 #'
 #' Get a table of all vanity URLs on the server. Requires administrator

R/ptype.R

@@ -246,5 +246,21 @@ connectapi_ptypes <- list(
     source = NA_character_,
     timestamp = NA_datetime_,
     data = NA_character_
+  ),
+  packages = tibble::tibble(
+    language = NA_character_,
+    language_version = NA_character_,
+    name = NA_character_,
+    version = NA_character_,
+    hash = NA_character_,
+    bundle_id = NA_character_,
+    app_id = NA_character_,
+    app_guid = NA_character_,
+  ),
+  content_packages = tibble::tibble(
+    language = NA_character_,
+    name = NA_character_,
+    version = NA_character_,
+    hash = NA_character_
   )
 )