Merge pull request #26 from nationalparkservice/dev

Dev

Author: wright13

.gitignore

@@ -6,3 +6,4 @@
 .quarto
 inst/doc
 scratchpad
+docs

DESCRIPTION

@@ -7,7 +7,7 @@ Description: Interact with the National Park Service (NPS) DataStore in R. NPS D
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3
 Suggests: 
     httptest2,
     knitr,

NAMESPACE

@@ -2,7 +2,6 @@
 
 export("%>%")
 export(active_directory_lookup)
-export(add_bibliography)
 export(add_external_link)
 export(add_keywords)
 export(add_reference_owners)
@@ -12,15 +11,20 @@ export(delete_all_keywords)
 export(delete_reference_owner)
 export(example_ref_ids)
 export(get_bibliography)
+export(get_by_for_nps)
 export(get_date_precision)
 export(get_external_links)
 export(get_file_info)
 export(get_keywords)
+export(get_lifecycle_info)
 export(get_reference_owners)
 export(get_reference_types)
 export(search_references_by_id)
 export(search_references_by_id_basic)
+export(set_bibliography)
+export(set_by_for_nps)
 export(set_file_info)
 export(set_license)
+export(set_lifecycle_active)
 export(upload_file_to_reference)
 importFrom(magrittr,"%>%")

NEWS.md

@@ -0,0 +1,9 @@
+# NPSdatastore (development version 2026-01-28)
+
+## New features
+  * added `set_by_for_nps()` which designates a reference as created by or for the NPS (or not)
+  * added `get_lifecycle_info()` which retrieves a reference's current lifecycle and indicates whether it can be altered
+  * added `set_lifecycle_active()` and `set_lifecycle_draft()`, allowing reference lifecycle to be changed
+
+## Enhancements
+  * updated pkgdown site with better organized function reference

R/get.R

@@ -355,3 +355,53 @@ get_bibliography <- function(reference_id, nps_internal = FALSE, dev = FALSE) {
 
   return(bib)
 }
+
+#' Determine if a reference was created by/for the NPS
+#'
+#' @inheritParams get_bibliography
+#'
+#' @returns TRUE if the reference was created by or for the NPS, FALSE if not.
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#'   by_for_nps <- get_by_for_nps(reference_id = 652358)
+#' }
+#'
+get_by_for_nps <- function(reference_id, nps_internal = FALSE, dev = FALSE) {
+  bib <- get_bibliography(reference_id, nps_internal, dev)
+  by_for_nps <- bib$isAgencyOriginated
+
+  return(by_for_nps)
+}
+
+#' Retrieve the current lifecycle status of a reference.
+#' Only works for internal NPS users.
+#'
+#' @inheritParams get_bibliography
+#'
+#' @returns A list of lifecycle information for the reference
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#'   lifecycle_info <- get_lifecycle_info(reference_id = 652358)
+#'   lifecycle = lifecycle_info$lifecycle
+#' }
+#'
+get_lifecycle_info <- function(reference_id, dev = FALSE) {
+  .validate_ref_id(reference_id)
+
+  nps_internal <- TRUE
+
+  lifecycle_info <- .datastore_request(is_secure = nps_internal, is_dev = dev) |>
+    httr2::req_url_path_append("Reference", reference_id, "LifecycleConstraints") |>
+    httr2::req_method("GET") |>
+    httr2::req_perform()
+
+  .validate_resp(lifecycle_info)
+
+  lifecycle_info <- httr2::resp_body_json(lifecycle_info)
+
+  return(lifecycle_info)
+}

R/helpers.R

@@ -5,25 +5,25 @@
 
 # datastore API base URL:
 assign("ds_public_api",
-       "https://irmaservices.nps.gov/datastore/v7/rest",
+       "https://irmaservices.nps.gov/datastore/v8/rest",
        envir = .pkgglobalenv
 )
 
 # datastore secure API base URL:
 assign("ds_secure_api",
-       "https://irmaservices.nps.gov/datastore-secure/v7/rest",
+       "https://irmaservices.nps.gov/datastore-secure/v8/rest",
        envir = .pkgglobalenv
 )
 
 # datastore secure dev api
 assign("ds_dev_secure_api",
-       "https://irmadevservices.nps.gov/datastore-secure/v7/rest",
+       "https://irmadevservices.nps.gov/datastore-secure/v8/rest",
        envir = .pkgglobalenv
 )
 
 # datastore dev API
 assign("ds_dev_public_api",
-       "https://irmadevservices.nps.gov/datastore/v7/rest",
+       "https://irmadevservices.nps.gov/datastore/v8/rest",
        envir = .pkgglobalenv
 )
 
@@ -62,7 +62,9 @@ globalVariables(c("public_refs",
                   "mimeType",
                   "downloadLink",
                   "is508Compliant",
-                  "fileSize_kb"))
+                  "fileSize_kb",
+                  "extensionAttribute2",
+                  "orcid"))
 
 
 #' Get the right base URL for the DataStore API
@@ -71,6 +73,7 @@ globalVariables(c("public_refs",
 #' @param is_dev Retrieve the dev version of the API base URL?
 #'
 #' @returns One of four base URLs for the DataStore API (public, secure, public+dev, secure+dev)
+#' @keywords internal
 #'
 .get_base_url <- function(is_secure, is_dev) {
   datastore_url <- dplyr::case_when(
@@ -89,6 +92,7 @@ globalVariables(c("public_refs",
 #' @inheritParams .get_base_url
 #'
 #' @returns The url to the reference profile page
+#' @keywords internal
 #'
 .get_ref_profile_url <- function(ref_id, is_dev) {
   ref_profile_url <- dplyr::case_when(
@@ -106,6 +110,7 @@ globalVariables(c("public_refs",
 #' @param suppress_errors Suppress HTTP errors? Set to TRUE if using `.validate_resp()`
 #'
 #' @returns A httr2 request object with curl options set to allow authentication for NPS users (if using secure API)
+#' @keywords internal
 #'
 .datastore_request <- function(is_secure, is_dev, suppress_errors = TRUE) {
   base_url <- .get_base_url(is_secure = is_secure, is_dev = is_dev)
@@ -132,6 +137,7 @@ globalVariables(c("public_refs",
 #' @inheritParams .get_base_url
 #'
 #' @returns List of reference profiles
+#' @keywords internal
 #'
 .get_reference_profiles <- function(reference_ids, is_secure, is_dev) {
   request <- .datastore_request(is_secure = is_secure, is_dev = is_dev) |>
@@ -169,6 +175,7 @@ globalVariables(c("public_refs",
 #' @param child_list_names The elements of the reference profile that should be converted to vectors
 #'
 #' @returns The tidied reference profile
+#' @keywords internal
 #'
 .lists2vectors <- function(parent_list, child_list_names) {
   for (child_list in child_list_names) {
@@ -188,6 +195,7 @@ globalVariables(c("public_refs",
 #' @param child_list_names The elements of the reference profile that should be converted to tibbles
 #'
 #' @returns The tidied reference profile
+#' @keywords internal
 #'
 .lists2tibbles <- function(parent_list, child_list_names) {
   for (child_list in child_list_names) {
@@ -245,6 +253,7 @@ example_ref_ids <- function(visibility = c("public", "internal", "both"), n, see
 #' @param multiple_ok Can ref_id be a vector of multiple IDs?
 #' @param arg Used to get the actual name of the argument in the calling function. See `?rlang::`topic-error-call``
 #' @param call The caller environment, for more helpful error messages. See `?rlang::`topic-error-call``
+#' @keywords internal
 #'
 .validate_ref_id <- function(ref_id, multiple_ok = FALSE,
                  arg = rlang::caller_arg(ref_id),
@@ -271,6 +280,22 @@ example_ref_ids <- function(visibility = c("public", "internal", "both"), n, see
 
 }
 
+.validate_lifecycle <- function(ref_id, expected_lifecycle = c("Draft", "Active"), is_dev,
+                                call = rlang::caller_env()) {
+
+  expected_lifecycle <- match.arg(expected_lifecycle, several.ok = FALSE)
+
+  # Get actual lifecycle
+  actual_lifecycle <- get_lifecycle_info(reference_id = ref_id, dev = is_dev)
+  actual_lifecycle <- actual_lifecycle$lifecycle
+
+  # Enforce is file, not folder
+  if (actual_lifecycle != expected_lifecycle) {
+    cli::cli_abort("Lifecycle for reference {ref_id} must be set to {expected_lifecycle}. It is currently set to {actual_lifecycle}.",
+                   call = call)
+  }
+}
+
 .validate_file_path <- function(file_path,
                                 arg = rlang::caller_arg(file_path),
                                 call = rlang::caller_env()) {
@@ -286,6 +311,25 @@ example_ref_ids <- function(visibility = c("public", "internal", "both"), n, see
   }
 }
 
+#' Validate TRUE/FALSE arguments
+#'
+#' @param bool Value to check
+#' @param arg Used to get the actual name of the argument in the calling function. See `?rlang::`topic-error-call``
+#' @param call The caller environment, for more helpful error messages. See `?rlang::`topic-error-call``
+#' @keywords internal
+#'
+.validate_truefalse <- function(bool,
+                             arg = rlang::caller_arg(bool),
+                             call = rlang::caller_env()) {
+
+  # Enforce a TRUE/FALSE value
+  if (!is.logical(bool) || is.na(bool)) {
+    cli::cli_abort("{.arg {arg}} is invalid. Must be logical (`TRUE` or `FALSE`).",
+                   call = call)
+  }
+
+}
+
 .validate_retry <- function(retry,
                             arg = rlang::caller_arg(retry),
                             call = rlang::caller_env()) {

R/set.R

@@ -471,6 +471,8 @@ add_external_link <- function(reference_id, url, description, last_verified = fo
 
 #' Replace the bibliography in a DataStore reference
 #'
+#' To update specific elements of the bibliography, use the "set_" functions for those elements instead.
+#'
 #' @param bibliography A list representing a DataStore bibliography. It is recommended that you retrieve the current bibliography using `get_bibliography()` and then modify it as needed.
 #' @inheritParams upload_file_to_reference
 #'
@@ -482,10 +484,10 @@ add_external_link <- function(reference_id, url, description, last_verified = fo
 #' bib <- get_bibliography(reference_id = 00000)
 #' bib$description <- "This is a new description for this reference"
 #' bib$notes <- "This reference is for testing purposes only"
-#' new_bib <- add_bibliography(reference_id = 00000, bibliography = bib, dev = TRUE)
+#' new_bib <- set_bibliography(reference_id = 00000, bibliography = bib, dev = TRUE)
 #' }
 #'
-add_bibliography <- function(reference_id, bibliography, dev = TRUE, interactive = TRUE) {
+set_bibliography <- function(reference_id, bibliography, dev = TRUE, interactive = TRUE) {
 
   .validate_ref_id(reference_id)
 
@@ -512,6 +514,56 @@ add_bibliography <- function(reference_id, bibliography, dev = TRUE, interactive
   return(bib)
 }
 
+#' Set the flag that indicates whether a reference was created by or for NPS
+#'
+#' @param by_for_nps TRUE or FALSE: was this reference created by or for NPS?
+#' @inheritParams upload_file_to_reference
+#'
+#' @returns A list representing the full updated bibliography.
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#' new_bib <- set_by_for_nps(reference_id = 000000, by_for_nps = TRUE)
+#' new_bib <- set_by_for_nps(reference_id = 000000, by_for_nps = TRUE, dev = FALSE)
+#' }
+set_by_for_nps <- function(reference_id, by_for_nps, dev = TRUE, interactive = TRUE) {
+
+  # Validate arguments
+  .validate_truefalse(by_for_nps)
+  .validate_ref_id(reference_id)
+
+  # Validate that reference is in draft mode, otherwise can't alter bibliography
+  .validate_lifecycle(ref_id = reference_id, expected_lifecycle = "Draft", is_dev = dev)
+
+  # Set values
+  nps_internal <- TRUE
+  by_for_nps <- dplyr::case_when(by_for_nps ~ 'true',
+                             !by_for_nps ~ 'false',
+                             .default = NA_character_)  # convert by_for_nps to a string for the API
+
+  # Verify that we're modifying the right reference
+  if (interactive) {
+    .user_validate_ref_title(ref_id = reference_id,
+                             is_secure = TRUE,
+                             is_dev = dev)
+  }
+
+  body <- list(isAgencyOriginated = by_for_nps)
+
+  bib <- .datastore_request(is_secure = TRUE, is_dev = dev) |>
+    httr2::req_url_path_append("Reference", reference_id, "Bibliography") |>
+    httr2::req_body_json(body) |>
+    httr2::req_method("PATCH") |>  # PATCH ensures that only the specified field (isAgencyOriginated) gets modified, not the whole bibliography
+    httr2::req_perform()
+
+  .validate_resp(bib)
+
+  bib <- httr2::resp_body_json(bib)
+
+  invisible(bib)
+}
+
 #' Add DataStore reference(s) to a Project reference
 #'
 #' @param project_id The reference ID of the Project
@@ -594,3 +646,64 @@ set_license <- function(reference_id, license_type_id, dev = TRUE, interactive =
 
   return(license_info)
 }
+
+
+#' Activate a reference
+#'
+#' Use with caution! It's usually a better idea to review the reference on the DataStore website and manually activate it.
+#'
+#' @inheritParams upload_file_to_reference
+#'
+#' @returns Invisibly returns the current lifecycle information for the reference
+#'
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#'   lifecycle_info <- set_lifecycle_active(reference_id = 652358)
+#' }
+#'
+set_lifecycle_active <- function(reference_id, dev = TRUE, interactive = TRUE) {
+  .validate_ref_id(reference_id)
+
+  lifecycle_info <- .datastore_request(is_secure = TRUE, is_dev = dev) |>
+    httr2::req_url_path_append("Reference", reference_id, "Lifecycle", "Active") |>
+    httr2::req_body_json(list()) |>
+    httr2::req_method("PUT") |>
+    httr2::req_perform()
+
+  .validate_resp(lifecycle_info)
+
+  lifecycle_info <- get_lifecycle_info(reference_id = reference_id, dev = dev)
+
+  invisible(lifecycle_info)
+}
+
+#' Set a reference to draft mode
+#'
+#' Use with extreme caution! You may not be able to reactivate via the API if you are working with an older reference that is missing multiple required fields.
+#'
+#' @inheritParams upload_file_to_reference
+#'
+#' @returns Invisibly returns the current lifecycle information for the reference
+#'
+#' @examples
+#' \dontrun{
+#'   lifecycle_info <- set_lifecycle_draft(reference_id = 652358)
+#' }
+#'
+set_lifecycle_draft <- function(reference_id, dev = TRUE, interactive = TRUE) {
+  .validate_ref_id(reference_id)
+
+  lifecycle_info <- .datastore_request(is_secure = TRUE, is_dev = dev) |>
+    httr2::req_url_path_append("Reference", reference_id, "Lifecycle", "Draft") |>
+    httr2::req_body_json(list()) |>
+    httr2::req_method("PUT") |>
+    httr2::req_perform()
+
+  .validate_resp(lifecycle_info)
+
+  lifecycle_info <- get_lifecycle_info(reference_id = reference_id, dev = dev)
+
+  invisible(lifecycle_info)
+}