Add reusable auth objects and auth arg to req_prepare()

NAMESPACE

@@ -2,6 +2,10 @@
 
 S3method(.add_body,json)
 S3method(.add_body,multipart)
+S3method(.as_nectar_auth,"NULL")
+S3method(.as_nectar_auth,default)
+S3method(.as_nectar_auth,list)
+S3method(.as_nectar_auth,nectar_auth)
 S3method(.as_nectar_request,default)
 S3method(.as_nectar_request,httr2_request)
 S3method(.as_nectar_request,nectar_request)

R/aaa-shared_params.R

@@ -6,7 +6,10 @@
 #'   where a request is coming from. We automatically include information about
 #'   your package and nectar, but use this to provide additional details.
 #'   Default `NULL`.
-#' @param api_key (`length-1 character`) The API key to use.
+#' @param api_key (`length-1 character` or `NULL`) The API key to use. If this
+#'   value is `NULL`, the key will be removed from the request. If this value is
+#'   `NA` or an empty string, the request is returned unchanged when the
+#'   prepared auth is applied.
 #' @param arg (`length-1 character`) An argument name as a string. This argument
 #'   will be mentioned in error messages as the input that is at the origin of a
 #'   problem.
@@ -33,6 +36,8 @@
 #'   other than `GET` or `POST`, supply it. Case is ignored.
 #' @param mime_type (`length-1 character`) The mime type of any files present in
 #'   the body. Some APIs allow you to leave this as NULL for them to guess.
+#' @param location (`length-1 character`) Where the API key should be passed.
+#'   One of `"header"` (default), `"query"`, or `"cookie"`.
 #' @param name (`length-1 character`) The name of a package or other thing to
 #'   add to or remove from the user agent string.
 #' @param pagination_fn (`function`) A function that takes the previous response
@@ -42,7 +47,8 @@
 #'   [httr2::iterate_with_offset()]. This function will be extracted from the
 #'   request by [req_perform_opinionated()] and passed on as `next_req` to
 #'   [httr2::req_perform_iterative()].
-#' @param parameter_name (`length-1 character`) The name to use for the API key.
+#' @param parameter_name (`length-1 character`) The name of the parameter to use
+#'   in the header, query, or cookie.
 #' @param path (`character` or `list`) The route to an API endpoint. Optionally,
 #'   a list or character vector with the path as one or more unnamed arguments
 #'   (which will be concatenated with "/") plus named arguments to

R/auth_prepare.R

@@ -8,26 +8,53 @@
 #' @param auth_fn (`function`) A function to use to authenticate a request.
 #' @returns A list with class `"nectar_auth"` and elements `auth_fn` and
 #'   `auth_args`.
-#' @family opinionated request functions
+#' @family opinionated auth functions
 #' @export
 #'
 #' @examples
 #' auth_prepare(req_auth_api_key, "X-API-Key", api_key = "my-api-key")
 auth_prepare <- function(auth_fn, ..., call = rlang::caller_env()) {
   auth_fn <- rlang::as_function(auth_fn, call = call)
-  structure(
+  .as_nectar_auth(
     list(auth_fn = auth_fn, auth_args = rlang::list2(...)),
-    class = "nectar_auth"
+    call = call
   )
 }
 
 .as_nectar_auth <- function(auth, call = rlang::caller_env()) {
-  if (is.null(auth)) {
-    return(list(auth_fn = NULL, auth_args = list()))
+  UseMethod(".as_nectar_auth")
+}
+
+#' @export
+.as_nectar_auth.nectar_auth <- function(auth, call = rlang::caller_env()) {
+  return(auth)
+}
+
+#' @export
+.as_nectar_auth.NULL <- function(auth, call = rlang::caller_env()) {
+  return(list(auth_fn = NULL, auth_args = list()))
+}
+
+#' @export
+.as_nectar_auth.list <- function(auth, call = rlang::caller_env()) {
+  if (!("auth_fn" %in% names(auth))) {
+    return(NextMethod())
   }
-  if (inherits(auth, "nectar_auth")) {
+  if (setequal(names(auth), c("auth_fn", "auth_args"))) {
+    class(auth) <- "nectar_auth"
     return(auth)
   }
+  structure(
+    list(
+      auth_fn = auth$auth_fn,
+      auth_args = auth[setdiff(names(auth), "auth_fn")]
+    ),
+    class = "nectar_auth"
+  )
+}
+
+#' @export
+.as_nectar_auth.default <- function(auth, call = rlang::caller_env()) {
   .nectar_abort(
     c(
       "{.arg {auth}} must be `NULL` or a {.cls nectar_auth}.",

R/req_auth_api_key.R

@@ -6,16 +6,9 @@
 #'
 #' @inheritParams .shared-params
 #' @inheritParams rlang::args_dots_empty
-#' @param parameter_name (`length-1 character`) The name of the parameter to use
-#'   in the header, query, or cookie.
-#' @param api_key (`length-1 character` or `NULL`) The API key to use. If this
-#'   value is `NULL`, the key will be removed from the request. If this value is
-#'   `NA` or an empty string, the request is returned unchanged when the
-#'   prepared auth is applied.
-#' @param location (`length-1 character`) Where the API key should be passed.
-#'   One of `"header"` (default), `"query"`, or `"cookie"`.
 #'
 #' @inherit .shared-request return
+#' @family opinionated auth functions, opinionated request functions
 #' @export
 #'
 #' @examples
@@ -69,17 +62,9 @@ req_auth_api_key <- function(
 #'
 #' @inheritParams .shared-params
 #' @inheritParams rlang::args_dots_empty
-#' @param parameter_name (`length-1 character`) The name of the parameter to use
-#'   in the header, query, or cookie.
-#' @param api_key (`length-1 character` or `NULL`) The API key to use. If this
-#'   value is `NULL`, the key will be removed from the request. If this value is
-#'   `NA` or an empty string, the request is returned unchanged when the
-#'   prepared auth is applied.
-#' @param location (`length-1 character`) Where the API key should be passed.
-#'   One of `"header"` (default), `"query"`, or `"cookie"`.
 #' @returns A list with class `"nectar_auth"` and elements `auth_fn` and
 #'   `auth_args`.
-#' @family opinionated request functions
+#' @family opinionated auth functions
 #' @export
 #'
 #' @examples

tests/testthat/test-auth_prepare.R

@@ -0,0 +1,9 @@
+test_that("auth_prepare() constructs nectar_auth objects (#81)", {
+  test_result <- auth_prepare(req_auth_api_key, "parm", api_key = "my_key")
+  expect_s3_class(test_result, "nectar_auth")
+  expect_identical(test_result$auth_fn, req_auth_api_key)
+  expect_identical(
+    test_result$auth_args,
+    list("parm", api_key = "my_key")
+  )
+})

tests/testthat/test-req_auth_api_key.R

@@ -12,17 +12,7 @@ test_that("req_auth_api_key errors informatively with unused arguments", {
   )
 })
 
-test_that("auth_prepare() constructs nectar_auth objects", {
-  test_result <- auth_prepare(req_auth_api_key, "parm", api_key = "my_key")
-  expect_s3_class(test_result, "nectar_auth")
-  expect_identical(test_result$auth_fn, req_auth_api_key)
-  expect_identical(
-    test_result$auth_args,
-    list("parm", api_key = "my_key")
-  )
-})
-
-test_that("auth_api_key() prepares req_auth_api_key auth", {
+test_that("auth_api_key() prepares req_auth_api_key auth (#81)", {
   test_result <- auth_api_key(
     parameter_name = "parm",
     api_key = "my_key",

tests/testthat/test-req_prepare.R

@@ -153,7 +153,7 @@ test_that("req_prepare() applies tidying", {
   )
 })
 
-test_that("req_prepare() applies prepared auth", {
+test_that("req_prepare() applies prepared auth (#81)", {
   test_result <- req_prepare(
     base_url = "https://example.com",
     auth = auth_prepare(req_auth_api_key, "parm", api_key = "my_key")
@@ -164,11 +164,11 @@ test_that("req_prepare() applies prepared auth", {
   )
 })
 
-test_that("req_prepare() errors for unsupported auth objects", {
+test_that("req_prepare() errors for unsupported auth objects (#81)", {
   expect_error(
     req_prepare(
       base_url = "https://example.com",
-      auth = list(auth_fn = req_auth_api_key, auth_args = list("parm"))
+      auth = "not_auth"
     ),
     class = "nectar-error-unsupported_auth_class"
   )