Implement gs4_scopes()

Closes #291

Author: jennybc

NAMESPACE

@@ -97,6 +97,7 @@ export(gs4_has_token)
 export(gs4_oauth_app)
 export(gs4_oauth_client)
 export(gs4_random)
+export(gs4_scopes)
 export(gs4_token)
 export(gs4_user)
 export(local_gs4_quiet)

NEWS.md

@@ -1,5 +1,11 @@
 # googlesheets4 (development version)
 
+* `gs4_scopes()` is a new function to access scopes relevant to the Sheets and
+  Drive APIs. When called without arguments, `gs4_scopes()` returns a named
+  vector of scopes, where the names are the associated short aliases.
+  `gs4_scopes()` can also be called with a character vector; any element that's
+  recognized as a short alias is replaced with the associated full scope (#291).
+
 # googlesheets4 1.1.0
 
 ## Syncing up with gargle

R/gs4_auth.R

@@ -20,6 +20,21 @@ gargle_lookup_table <- list(
 #' @eval gargle:::PREFIX_auth_details(gargle_lookup_table)
 #' @eval gargle:::PREFIX_auth_params()
 #'
+#' @param scopes One or more API scopes. Each scope can be specified in full or,
+#'   for Sheets API-specific scopes, in an abbreviated form that is recognized by
+#'   [gs4_scopes()]:
+#'   * "spreadsheets" = "https://www.googleapis.com/auth/spreadsheets"
+#'     (the default)
+#'   * "spreadsheets.readonly" =
+#'     "https://www.googleapis.com/auth/spreadsheets.readonly"
+#'   * "drive" = "https://www.googleapis.com/auth/drive"
+#'   * "drive.readonly" = "https://www.googleapis.com/auth/drive.readonly"
+#'   * "drive.file" = "https://www.googleapis.com/auth/drive.file"
+#'
+#'   See
+#'   <https://developers.google.com/identity/protocols/oauth2/scopes#sheets> for
+#'   details on the permissions for each scope.
+#'
 #' @family auth functions
 #' @export
 #'
@@ -36,19 +51,19 @@ gargle_lookup_table <- list(
 #' gs4_auth(email = NA)
 #'
 #' # use a 'read only' scope, so it's impossible to edit or delete Sheets
-#' gs4_auth(
-#'   scopes = "https://www.googleapis.com/auth/spreadsheets.readonly"
+#' gs4_auth(scopes = "spreadsheets.readonly")
 #' )
 #'
 #' # use a service account token
 #' gs4_auth(path = "foofy-83ee9e7c9c48.json")
 gs4_auth <- function(email = gargle::gargle_oauth_email(),
                      path = NULL,
-                     scopes = "https://www.googleapis.com/auth/spreadsheets",
+                     scopes = "spreadsheets",
                      cache = gargle::gargle_oauth_cache(),
                      use_oob = gargle::gargle_oob_default(),
                      token = NULL) {
   gargle::check_is_service_account(path, hint = "gs4_auth_configure")
+  scopes <- gs4_scopes(scopes)
 
   # I have called `gs4_auth(token = drive_token())` multiple times now,
   # without attaching googledrive. Expose this error noisily, before it gets
@@ -259,6 +274,48 @@ check_gs4_email_is_drive_email <- function() {
   }
 }
 
+#' Produce scopes specific to the Sheets API
+#'
+#' When called with no arguments, `gs4_scopes()` returns a named character
+#' vector of scopes associated with the Sheets API. If `gs4_scopes(scopes =)` is
+#' given, an abbreviated entry such as `"sheets.readonly"` is expanded to a full
+#' scope (`"https://www.googleapis.com/auth/sheets.readonly"` in this case).
+#' Unrecognized scopes are passed through unchanged.
+#'
+#' @inheritParams gs4_auth
+#'
+#' @seealso
+#'   <https://developers.google.com/identity/protocols/oauth2/scopes#sheets> for
+#'   details on the permissions for each scope.
+#' @returns A character vector of scopes.
+#' @family auth functions
+#' @export
+#' @examples
+#' gs4_scopes("spreadsheets")
+#' gs4_scopes("spreadsheets.readonly")
+#' gs4_scopes("drive")
+#' gs4_scopes()
+gs4_scopes <- function(scopes = NULL) {
+  if (is.null(scopes)) {
+    sheets_scopes
+  } else {
+    resolve_scopes(user_scopes = scopes, package_scopes = sheets_scopes)
+  }
+}
+
+sheets_scopes <- c(
+  spreadsheets          = "https://www.googleapis.com/auth/spreadsheets",
+  spreadsheets.readonly = "https://www.googleapis.com/auth/spreadsheets.readonly",
+  drive                 = "https://www.googleapis.com/auth/drive",
+  drive.readonly        = "https://www.googleapis.com/auth/drive.readonly",
+  drive.file            = "https://www.googleapis.com/auth/drive.file"
+)
+
+resolve_scopes <- function(user_scopes, package_scopes) {
+  m <- match(user_scopes, names(package_scopes))
+  ifelse(is.na(m), user_scopes, package_scopes[m])
+}
+
 # unexported helpers that are nice for internal use ----
 gs4_auth_internal <- function(account = c("docs", "testing"),
                               scopes = NULL,

man/gs4_auth.Rd

@@ -108,6 +108,7 @@ reference:
     - gs4_deauth
     - gs4_user
     - gs4_auth_configure
+    - gs4_scopes
     - googlesheets4-configuration
   - title: "Programming around the Sheets API"
     desc: >

man/gs4_auth_configure.Rd

@@ -24,3 +24,19 @@
       The `app` argument of `gs4_auth_configure()` is deprecated as of googlesheets4 1.1.0.
       i Please use the `client` argument instead.
 
+# gs4_scopes() reveals Sheets scopes
+
+    Code
+      gs4_scopes()
+    Output
+                                                 spreadsheets 
+               "https://www.googleapis.com/auth/spreadsheets" 
+                                        spreadsheets.readonly 
+      "https://www.googleapis.com/auth/spreadsheets.readonly" 
+                                                        drive 
+                      "https://www.googleapis.com/auth/drive" 
+                                               drive.readonly 
+             "https://www.googleapis.com/auth/drive.readonly" 
+                                                   drive.file 
+                 "https://www.googleapis.com/auth/drive.file" 
+

man/gs4_deauth.Rd

@@ -57,3 +57,37 @@ test_that("gs4_auth_configure(app =) is deprecated in favor of client", {
   expect_equal(gs4_oauth_client()$id, "abc.apps.googleusercontent.com")
 })
 
+# gs4_scopes() ----
+test_that("gs4_scopes() reveals Sheets scopes", {
+  expect_snapshot(gs4_scopes())
+})
+
+test_that("gs4_scopes() substitutes actual scope for short form", {
+  expect_equal(
+    gs4_scopes(c(
+      "spreadsheets",
+      "drive",
+      "drive.readonly"
+    )),
+    c(
+      "https://www.googleapis.com/auth/spreadsheets",
+      "https://www.googleapis.com/auth/drive",
+      "https://www.googleapis.com/auth/drive.readonly"
+    )
+  )
+})
+
+test_that("gs4_scopes() passes unrecognized scopes through", {
+  expect_equal(
+    gs4_scopes(c(
+      "email",
+      "spreadsheets.readonly",
+      "https://www.googleapis.com/auth/cloud-platform"
+    )),
+    c(
+      "email",
+      "https://www.googleapis.com/auth/spreadsheets.readonly",
+      "https://www.googleapis.com/auth/cloud-platform"
+    )
+  )
+})