feat: add function to get integrations (#426)

Author: toph-allen

DESCRIPTION

@@ -78,6 +78,7 @@ Collate:
     'get.R'
     'git.R'
     'groups.R'
+    'integrations.R'
     'lazy.R'
     'page.R'
     'parse.R'

NAMESPACE

@@ -6,8 +6,10 @@ S3method("[[",connect_tag_tree)
 S3method(api_build,op_base_connect)
 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_tibble,connect_list_hits)
+S3method(as_tibble,connect_list_integrations)
 S3method(connect_vars,op_base)
 S3method(connect_vars,op_single)
 S3method(connect_vars,tbl_connect)
@@ -84,6 +86,7 @@ export(get_group_members)
 export(get_group_permission)
 export(get_groups)
 export(get_image)
+export(get_integrations)
 export(get_job)
 export(get_job_list)
 export(get_jobs)

NEWS.md

@@ -5,6 +5,9 @@
 - New `get_usage()` function returns content usage data from Connect's `GET
   v1/instrumentation/content/hits` endpoint on Connect v2025.04.0 and higher.
   (#390)
+- New `get_integrations()` function lists all OAuth integrations available on the
+  Connect server from the `GET v1/oauth/integrations` endpoint on Connect v2024.12.0
+  and higher. (#413)
 
 ## Enhancements and fixes
 

R/get.R

@@ -820,6 +820,8 @@ get_procs <- function(src) {
 #' Please see https://docs.posit.co/connect/user/oauth-integrations/#obtaining-a-viewer-oauth-access-token
 #' for more information.
 #'
+#' @seealso [get_integrations()], [get_oauth_content_credentials()]
+#'
 #' @export
 get_oauth_credentials <- function(
   connect,
@@ -886,6 +888,8 @@ get_oauth_credentials <- function(
 #' Please see https://docs.posit.co/connect/user/oauth-integrations/#obtaining-a-service-account-oauth-access-token
 #' for more information.
 #'
+#' @seealso [get_integrations()], [get_oauth_credentials()]
+#'
 #' @export
 get_oauth_content_credentials <- function(
   connect,

R/integrations.R

@@ -0,0 +1,106 @@
+#' List all OAuth integrations on the Connect server
+#'
+#' @description
+#' Retrieve information about all OAuth integrations available to Posit Connect.
+#' You must have administrator or publisher privileges to perform this action.
+#'
+#' @param client A `Connect` R6 client object.
+#'
+#' @return A list of OAuth integrations. Each integration is a list with the
+#'   following elements (all character strings unless indicated otherwise):
+#'
+#'   * `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 sub-list 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
+#' parsed types. In the resulting data frame:
+#'
+#'   * `created_time` and `updated_time` are parsed to `POSIXct`.
+#'   * `config` remains as a list-column.
+#'
+#' @seealso [get_oauth_credentials()], [get_oauth_content_credentials()]
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#'
+#' # Fetch all OAuth integrations
+#' integrations <- get_integrations(client)
+#'
+#'
+#' # Update the configuration and metadata for a subset of integrations.
+#' json_payload <- toJSON(list(
+#'   description = "New Description",
+#'   config = list(
+#'     client_secret = "new-client-secret"
+#'   )
+#' ), auto_unbox = TRUE)
+#'
+#' results <- integrations |>
+#'   purrr::keep(\(x) x$template == "service_to_update") |>
+#'   purrr::map(\(x) client$PATCH(paste0("v1/oauth/integrations/", x$guid), body = json_payload))
+#'
+#'
+#' # Convert to tibble or data frame
+#' integrations_df <- tibble::as_tibble(integrations)
+#' }
+#'
+#' @export
+get_integrations <- function(client) {
+  error_if_less_than(client$version, "2024.12.0")
+  integrations <- client$GET(v1_url("oauth", "integrations"))
+  class(integrations) <- c("connect_list_integrations", class(integrations))
+  integrations
+}
+
+#' Convert integrations data to a data frame
+#'
+#' @description
+#' Converts an list returned by [get_integrations()] into a data frame.
+#'
+#' @param x A `connect_list_integrations` object (from [get_integrations()]).
+#' @param row.names Passed to [base::as.data.frame()].
+#' @param optional Passed to [base::as.data.frame()].
+#' @param ... Passed to [base::as.data.frame()].
+#'
+#' @return A `data.frame` with one row per integration.
+#' @export
+as.data.frame.connect_list_integrations <- function(
+  x,
+  row.names = NULL, # nolint
+  optional = FALSE,
+  ...
+) {
+  integrations_tbl <- as_tibble(x)
+  as.data.frame(
+    integrations_tbl,
+    row.names = row.names,
+    optional = optional,
+    ...
+  )
+}
+
+#' Convert integrations data to a tibble
+#'
+#' @description
+#' Converts a list returned by [get_integrations()] to a tibble.
+#'
+#' @param x A `connect_list_integrations` object.
+#' @param ... Unused.
+#'
+#' @return A tibble with one row per integration.
+#' @export
+as_tibble.connect_list_integrations <- function(x, ...) {
+  parse_connectapi_typed(x, connectapi_ptypes$integrations)
+}

R/ptype.R

@@ -271,5 +271,16 @@ connectapi_ptypes <- list(
     name = NA_character_,
     version = NA_character_,
     hash = NA_character_
+  ),
+  integrations = tibble::tibble(
+    id = NA_character_,
+    guid = NA_character_,
+    created_time = NA_datetime_,
+    updated_time = NA_datetime_,
+    name = NA_character_,
+    description = NA_character_,
+    template = NA_character_,
+    auth_type = NA_character_,
+    config = NA_list_
   )
 )

_pkgdown.yml

@@ -69,6 +69,8 @@ reference:
       - starts_with("get")
       - as.data.frame.connect_list_hits
       - as_tibble.connect_list_hits
+      - as.data.frame.connect_list_integrations
+      - as_tibble.connect_list_integrations
 
   - title: "Other"
     desc: >