feat: support new metrics firehose api with get_usage()

.lintr

@@ -1,7 +1,7 @@
 linters: linters_with_defaults(
   line_length_linter = line_length_linter(120L),
   object_name_linter = object_name_linter(styles = c("snake_case", "symbols", "CamelCase")),
-  cyclocomp_linter = cyclocomp_linter(30L),
+  cyclocomp_linter = NULL, # Issues with R6 classes.
   object_length_linter(32L),
   indentation_linter = indentation_linter(hanging_indent_style = "tidy"),
   return_linter = NULL

NAMESPACE

@@ -98,6 +98,7 @@ export(get_tag_data)
 export(get_tags)
 export(get_thumbnail)
 export(get_timezones)
+export(get_usage)
 export(get_usage_shiny)
 export(get_usage_static)
 export(get_user_permission)

NEWS.md

@@ -1,5 +1,10 @@
 # connectapi (development version)
 
+## New features
+
+- 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)
 
 ## Enhancements and fixes
 

R/connect.R

@@ -818,6 +818,33 @@ Connect <- R6::R6Class(
       self$GET(path, query = query)
     },
 
+    #' @description Get content usage data.
+    #' @param from Optional `Date` or `POSIXt`; start of the time window. If a
+    #' `Date`, coerced to `YYYY-MM-DDT00:00:00` in the caller's time zone.
+    #' @param to Optional `Date` or `POSIXt`; end of the time window. If a
+    #' `Date`, coerced to `YYYY-MM-DDT23:59:59` in the caller's time zone.
+    inst_content_hits = function(from = NULL, to = NULL) {
+      error_if_less_than(self$version, "2025.04.0")
+
+      # If this is called with date objects with no timestamp attached, it's
+      # reasonable to assume that the caller is indicating the days as an
+      # inclusive range.
+      if (inherits(from, "Date")) {
+        from <- as.POSIXct(paste(from, "00:00:00"))
+      }
+      if (inherits(to, "Date")) {
+        to <- as.POSIXct(paste(to, "23:59:59"))
+      }
+
+      self$GET(
+        v1_url("instrumentation", "content", "hits"),
+        query = list(
+          from = make_timestamp(from),
+          to = make_timestamp(to)
+        )
+      )
+    },
+
     #' @description Get running processes.
     procs = function() {
       warn_experimental("procs")

R/get.R

@@ -526,6 +526,72 @@ get_usage_static <- function(
   return(out)
 }
 
+#' Get usage information for deployed content
+#'
+#' @description
+
+#' Retrieve content hits for all available content on the server. Available
+#' content depends on the user whose API key is in use. Administrator accounts
+#' will receive data for all content on the server. Publishers will receive data
+#' for all content they own or collaborate on.
+#'
+#' If no date-times are provided, all usage data will be returned.
+
+#' @param client A `Connect` R6 client object.
+#' @param from Optional `Date` or date-time (`POSIXct` or `POSIXlt`). Only
+#'   records after this time are returned. If a `Date`, treated as the start of
+#'   that day in the local time zone; if a date-time, used verbatim.
+#' @param to Optional `Date` or date-time (`POSIXct` or `POSIXlt`). Only records
+#'   before this time are returned. If a `Date`, treated as end of that day
+#'   (`23:59:59`) in the local time zone; if a date-time, used verbatim.
+#'
+#' @return A tibble with columns:
+#' * `id`: An identifier for the record.
+#' * `user_guid`: The GUID of logged-in visitors, NA for anonymous.
+#' * `content_guid`: The GUID of the content.
+#' * `timestamp`: The time of the hit as `POSIXct`.
+#' * `path`: The path of the hit. Not recorded for all content types.
+#' * `user_agent`: If available, the user agent string for the hit. Not
+#'   available for all records.
+#'
+#' @details
+#'
+#' The data returned by `get_usage()` includes all content types. For Shiny
+#' content, the `timestamp` indicates the *start* of the Shiny session.
+#' Additional fields for Shiny and non-Shiny are available respectively from
+#' `get_usage_shiny()` and `get_usage_static()`.
+#'
+#' When possible, however, we recommend using `get_usage()` over
+#' `get_usage_static()` or `get_usage_shiny()`, as it will be much faster for
+#' large datasets.
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#'
+#' # Fetch the last 2 days of hits
+#' usage <- get_usage(client, from = Sys.Date() - 2, to = Sys.Date())
+#'
+#' # Fetch usage after a specified date
+#' usage <- get_usage(
+#'   client,
+#'   from = as.POSIXct("2025-05-02 12:40:00", tz = "UTC")
+#' )
+#'
+#' # Fetch all usage
+#' usage <- get_usage(client)
+#' }
+#'
+#' @export
+get_usage <- function(client, from = NULL, to = NULL) {
+  usage_raw <- client$inst_content_hits(
+    from = from,
+    to = to
+  )
+
+  usage <- parse_connectapi_typed(usage_raw, connectapi_ptypes$usage)
+  fast_unnest_character(usage, "data")
+}
 
 #' Get Audit Logs from Posit Connect Server
 #'

R/parse.R

@@ -58,15 +58,19 @@ ensure_column <- function(data, default, name) {
       # manual fix because vctrs::vec_cast cannot cast double -> datetime or char -> datetime
       col <- coerce_datetime(col, default, name = name)
     }
+
     if (inherits(default, "fs_bytes") && !inherits(col, "fs_bytes")) {
       col <- coerce_fsbytes(col, default)
     }
+
     if (inherits(default, "integer64") && !inherits(col, "integer64")) {
       col <- bit64::as.integer64(col)
     }
+
     if (inherits(default, "list") && !inherits(col, "list")) {
       col <- list(col)
     }
+
     col <- vctrs::vec_cast(col, default, x_arg = name)
   }
   data[[name]] <- col
@@ -101,6 +105,65 @@ parse_connectapi <- function(data) {
   ))
 }
 
+# nolint start
+# Unnests a list column similarly to `tidyr::unnest_wider()`, bringing the
+# entries of each list-item up to the top level. Makes some simplifying
+# assumptions for the sake of performance:
+# 1. All inner variables are treated as character vectors;
+# 2. The names of the first entry of the list-column are used as the
+#    names of variables to extract.
+# Performance example:
+# > nrow(x_raw)
+# [1] 373632
+# > nrow(x_raw)
+# [1] 373632
+# > t_tidyr <- system.time(
+# +   x_tidyr <- tidyr::unnest_wider(x_raw, data)
+# + )
+# > t_custom <- system.time(
+# +   x_custom <- fast_unnest_character(x_raw, "data")
+# + )
+# > identical(x_tidyr, x_custom)
+# [1] TRUE
+# > t_tidyr
+#    user  system elapsed
+#   7.018   0.137   7.172
+# > t_custom
+#    user  system elapsed
+#   0.281   0.005   0.285
+# nolint end
+fast_unnest_character <- function(df, col_name) {
+  if (!is.character(col_name)) {
+    stop("col_name must be a character vector")
+  }
+  if (!col_name %in% names(df)) {
+    stop("col_name is not present in df")
+  }
+
+  list_col <- df[[col_name]]
+
+  new_cols <- names(list_col[[1]])
+
+  df2 <- df
+  for (col in new_cols) {
+    df2[[col]] <- vapply(
+      list_col,
+      function(row) {
+        if (is.null(row[[col]])) {
+          NA_character_
+        } else {
+          row[[col]]
+        }
+      },
+      "1",
+      USE.NAMES = FALSE
+    )
+  }
+
+  df2[[col_name]] <- NULL
+  df2
+}
+
 coerce_fsbytes <- function(x, to, ...) {
   if (is.numeric(x)) {
     fs::as_fs_bytes(x)

R/ptype.R

@@ -1,5 +1,5 @@
 NA_datetime_ <- # nolint: object_name_linter
-  vctrs::new_datetime(NA_real_, tzone = "UTC")
+  vctrs::new_datetime(NA_real_, tzone = Sys.timezone())
 NA_list_ <- # nolint: object_name_linter
   list(list())
 
@@ -38,6 +38,13 @@ connectapi_ptypes <- list(
     "bundle_id" = NA_character_,
     "data_version" = NA_integer_
   ),
+  usage = tibble::tibble(
+    "id" = NA_integer_,
+    "user_guid" = NA_character_,
+    "content_guid" = NA_character_,
+    "timestamp" = NA_datetime_,
+    "data" = NA_list_
+  ),
   content = tibble::tibble(
     "guid" = NA_character_,
     "name" = NA_character_,

tests/testthat/2025.04.0/__api__/v1/instrumentation/content/hits-c331ad.json

@@ -0,0 +1,52 @@
+[
+    {
+        "id": 8966707,
+        "user_guid": null,
+        "content_guid": "475618c9",
+        "timestamp": "2025-04-30T12:49:16.269904Z",
+        "data": {
+            "path": "/hello",
+            "user_agent": "Datadog/Synthetics"
+        }
+    },
+    {
+        "id": 8966708,
+        "user_guid": null,
+        "content_guid": "475618c9",
+        "timestamp": "2025-04-30T12:49:17.002848Z",
+        "data": {
+            "path": "/world",
+            "user_agent": null
+        }
+    },
+    {
+        "id": 8967206,
+        "user_guid": null,
+        "content_guid": "475618c9",
+        "timestamp": "2025-04-30T13:01:47.40738Z",
+        "data": {
+            "path": "/chinchilla",
+            "user_agent": "Datadog/Synthetics"
+        }
+    },
+    {
+        "id": 8967210,
+        "user_guid": null,
+        "content_guid": "475618c9",
+        "timestamp": "2025-04-30T13:04:13.176791Z",
+        "data": {
+            "path": "/lava-lamp",
+            "user_agent": "Datadog/Synthetics"
+        }
+    },
+    {
+        "id": 8966214,
+        "user_guid": "fecbd383",
+        "content_guid": "b0eaf295",
+        "timestamp": "2025-04-30T12:36:13.818466Z",
+        "data": {
+            "path": null,
+            "user_agent": null
+        }
+    }
+]