feat: function to set all oauth integrations associated with a content item

NAMESPACE

@@ -8,6 +8,8 @@ S3method(api_build,op_head)
 S3method(as.data.frame,connect_list_hits)
 S3method(as.data.frame,connect_list_integrations)
 S3method(as.data.frame,tbl_connect)
+S3method(as_integration,default)
+S3method(as_integration,list)
 S3method(as_tibble,connect_list_hits)
 S3method(as_tibble,connect_list_integrations)
 S3method(connect_vars,op_base)
@@ -16,6 +18,7 @@ S3method(connect_vars,tbl_connect)
 S3method(dim,tbl_connect)
 S3method(dimnames,tbl_connect)
 S3method(head,tbl_connect)
+S3method(print,connect_integration)
 S3method(print,connect_tag_tree)
 S3method(print,tbl_connect)
 export("%>%")
@@ -50,6 +53,7 @@ export(content_list_guid_has_access)
 export(content_list_with_permissions)
 export(content_render)
 export(content_restart)
+export(content_set_integrations)
 export(content_title)
 export(content_update)
 export(content_update_access_type)
@@ -86,6 +90,7 @@ export(get_group_members)
 export(get_group_permission)
 export(get_groups)
 export(get_image)
+export(get_integration)
 export(get_integrations)
 export(get_job)
 export(get_job_list)

NEWS.md

@@ -1,5 +1,10 @@
 # connectapi (development version)
 
+- New `content_set_integrations()` function to set the OAuth integration
+  associations for a content item. (#414)
+- New `get_integration()` function to retrieve details of a specific OAuth integration
+  from a Connect server. (#431)
+
 # connectapi 0.8.0
 
 ## Breaking changes

R/content.R

@@ -1434,3 +1434,72 @@ get_content_packages <- function(content) {
   res <- content$packages()
   parse_connectapi_typed(res, connectapi_ptypes$content_packages)
 }
+
+# Integrations ----
+
+#' Set all OAuth integration associations for a content item
+#'
+#' @description
+#' Removes any existing OAuth integration associations for a content item, and
+#' creates associations with the integrations provided. You must have
+#' administrator or publisher privileges to perform this action.
+#'
+#' @param content A `Content` R6 object representing the content item to modify.
+#' @param integrations A single `connect_integration` object or a list of
+#'   `connect_integration` objects to associate with this content.
+#'
+#' @return Invisibly returns `NULL`. A message is printed on success.
+#'
+#' @seealso
+#' [get_integrations()], [get_integration()], [content_item()]
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#'
+#' content <- content_item(client, "12345678-90ab-cdef-1234-567890abcdef")
+#'
+#' integrations <- get_integrations(client)
+#'
+#' # Associate a single integration
+#' github_integration <- purrr::keep(integrations, \(x) x$template == "github")[[1]]
+#' content_set_integrations(content, github_integration)
+#'
+#' # Associate multiple integrations at once
+#' selected_integrations <- integrations[1:2]
+#' content_set_integrations(content, selected_integrations)
+#' }
+#'
+#' @family oauth integration functions
+#' @family content functions
+#' @export
+content_set_integrations <- function(content, integrations) {
+  validate_R6_class(content, "Content")
+  # Handle a single integration
+  if (inherits(integrations, "connect_integration")) {
+    integrations <- list(integrations)
+  } else if (!inherits(integrations, "list")) {
+    stop(
+      "`integrations` must be a `connect_integration` class object or a list ",
+      "of `connect_integration` objects."
+    )
+  }
+  # Ensure that all the items we've been passed are integrations
+  if (!purrr::every(integrations, ~ inherits(.x, "connect_integration"))) {
+    stop("All items must be `connect_integration` objects")
+  }
+
+  payload <- purrr::map(integrations, ~ list(oauth_integration_guid = .x$guid))
+
+  content$connect$PUT(
+    v1_url(
+      "content",
+      content$content$guid,
+      "oauth",
+      "integrations",
+      "associations"
+    ),
+    body = payload
+  )
+  invisible(NULL)
+}

R/integrations.R

@@ -20,7 +20,7 @@
 #'   * `template`: The template used to configure this OAuth integration.
 #'   * `auth_type`: The authentication type indicates which OAuth flow is used by
 #'     this integration.
-#'   * `config`: A sub-list list with the OAuth integration configuration. Fields
+#'   * `config`: A list with the OAuth integration configuration. Fields
 #'     differ between integrations.
 #'
 #' Use [as.data.frame()] or [tibble::as_tibble()] to convert to a data frame with
@@ -29,7 +29,8 @@
 #'   * `created_time` and `updated_time` are parsed to `POSIXct`.
 #'   * `config` remains as a list-column.
 #'
-#' @seealso [get_oauth_credentials()], [get_oauth_content_credentials()]
+#' @seealso [get_oauth_credentials()], [get_oauth_content_credentials()],
+#' [get_integration()]
 #'
 #' @examples
 #' \dontrun{
@@ -56,15 +57,18 @@
 #' integrations_df <- tibble::as_tibble(integrations)
 #' }
 #'
+#' @family oauth integration functions
 #' @export
 get_integrations <- function(client) {
+  validate_R6_class(client, "Connect")
   error_if_less_than(client$version, "2024.12.0")
   integrations <- client$GET(v1_url("oauth", "integrations"))
+  integrations <- lapply(integrations, as_integration)
   class(integrations) <- c("connect_list_integrations", class(integrations))
   integrations
 }
 
-#' Convert integrations data to a data frame
+#' Convert integrations list to a data frame
 #'
 #' @description
 #' Converts an list returned by [get_integrations()] into a data frame.
@@ -91,7 +95,7 @@ as.data.frame.connect_list_integrations <- function(
   )
 }
 
-#' Convert integrations data to a tibble
+#' Convert integrations list to a tibble
 #'
 #' @description
 #' Converts a list returned by [get_integrations()] to a tibble.
@@ -104,3 +108,78 @@ as.data.frame.connect_list_integrations <- function(
 as_tibble.connect_list_integrations <- function(x, ...) {
   parse_connectapi_typed(x, connectapi_ptypes$integrations)
 }
+
+# Integration class ----
+
+#' Convert objects to integration class
+#'
+#' @param x An object to convert to an integration
+#'
+#' @return An integration object
+as_integration <- function(x) {
+  UseMethod("as_integration")
+}
+
+#' @export
+as_integration.default <- function(x) {
+  stop(
+    "Cannot convert object of class '",
+    class(x)[1],
+    "' to an integration"
+  )
+}
+
+#' @export
+as_integration.list <- function(x) {
+  structure(x, class = c("connect_integration", "list"))
+}
+
+#' @export
+print.connect_integration <- function(x, ...) {
+  cat("Integration:", x$name, "\n")
+  cat("GUID:", x$guid, "\n")
+  cat("Template:", x$template, "\n")
+  invisible(x)
+}
+
+#' Get the details of an OAuth integration
+#'
+#' @description
+#' Given the GUID of an OAuth integration available on a Connect server, retrieve
+#' its details. You must have administrator or publisher privileges to perform
+#' this action.
+#'
+#' @param client A `Connect` R6 client object.
+#' @param guid The GUID of an integration available on the Connect server.
+#'
+#' @return A `connect_integration` object representing an OAuth integration,
+#' which has the following fields:
+#'
+#'   * `id`: The internal identifier of this OAuth integration.
+#'   * `guid`: The GUID of this OAuth integration.
+#'   * `created_time`: The timestamp (RFC3339) indicating when this integration
+#'     was created.
+#'   * `updated_time`: The timestamp (RFC3339) indicating when this integration
+#'     was last updated
+#'   * `name`: A descriptive name to identify the OAuth integration.
+#'   * `description`: A brief text to describe the OAuth integration.
+#'   * `template`: The template used to configure this OAuth integration.
+#'   * `auth_type`: The authentication type indicates which OAuth flow is used by
+#'     this integration.
+#'   * `config`: A list with the OAuth integration configuration. Fields
+#'     differ between integrations.
+#'
+#' @seealso [get_oauth_credentials()], [get_oauth_content_credentials()], [get_integrations()]
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#' x <- get_integration(client, guid)
+#' }
+#'
+#' @family oauth integration functions
+#' @export
+get_integration <- function(client, guid) {
+  validate_R6_class(client, "Connect")
+  as_integration(client$GET(v1_url("oauth", "integrations", guid)))
+}

_pkgdown.yml

@@ -62,6 +62,16 @@ reference:
     contents:
       - matches("repo")
 
+  - title: "OAuth Integrations"
+    desc: >
+      Functions to work with OAuth integrations
+    contents:
+      - matches("integration")
+      - content_set_integrations
+      - get_integrations
+      - get_oauth_credentials
+      - get_oauth_content_credentials
+
   - title: "Reporting"
     desc: >
       Helpers to "get" data out of Connect