Add a whoami function (user, token, scopes); closes #39 (#51)

* Add a whoami function (user, token, scopes)

* documentation

* unrelated typos

* roxygenize

* better pointer to help

* link to gh_whoami() help from gh help

* test gh_whoami()

* Announce mocking status when recording

* Add additional classes to returned error objects (#50)

This allows you to catch a github_error or the exact status code
directly.

* Record tests (sort of, see below) in test-error.R

Note: there's only one new recording because the second test matches against first recording. It just happens to pass in a happy coincidence.

* Improve and record tests of gh_whoami()

* Make GITHUB_TOKEN be non-NULL on travis and appveyor

* Don't run any example re: gh_whoami()

* Use if() {} else {} when forming Authorization header

* Use gh() instead of low-level fxns in gh_whoami()

.travis.yml

@@ -7,5 +7,9 @@ r:
  - devel
  - oldrel
 
+env:
+  - global
+    - GITHUB_TOKEN=ANYTHING_BUT_NULL
+
 after_success:
   - test $TRAVIS_R_VERSION_STRING = "release" && Rscript -e 'covr::codecov()'

NAMESPACE

@@ -7,6 +7,7 @@ export(gh_last)
 export(gh_next)
 export(gh_prev)
 export(gh_tree_remote)
+export(gh_whoami)
 importFrom(httr,DELETE)
 importFrom(httr,GET)
 importFrom(httr,PATCH)

R/gh_request.R

@@ -118,9 +118,11 @@ gh_token <- function() {
 }
 
 gh_auth <- function(token) {
-  auth <- character()
-  if (token != "") auth <- c("Authorization" = paste("token", token))
-  auth
+  if (isTRUE(token != "")) {
+    c("Authorization" = paste("token", token))
+  } else {
+    character()
+  }
 }
 
 gh_send_headers <- function(headers = NULL) {

R/gh_whoami.R

@@ -0,0 +1,73 @@
+#' Info on current GitHub user and token
+#'
+#' Reports wallet name, GitHub login, and GitHub URL for the current
+#' authenticated user, the first few and last characters of the token, and the
+#' associated scopes.
+#'
+#' Get a personal access token for the GitHub API from
+#' \url{https://github.com/settings/tokens} and select the scopes necessary for
+#' your planned tasks. The \code{repo} scope, for example, is one many are
+#' likely to need. The token itself is a string of 40 letters and digits. You
+#' can store it any way you like and provide explicitly via the \code{.token}
+#' argument to \code{\link{gh}()}.
+#'
+#' However, many prefer to define an environment variable \code{GITHUB_PAT} (or
+#' \code{GITHUB_TOKEN}) with this value in their \code{.Renviron} file. Add a
+#' line that looks like this, substituting your PAT:
+#'
+#' \preformatted{
+#' GITHUB_PAT=8c70fd8419398999c9ac5bacf3192882193cadf2
+#' }
+#'
+#' Put a line break at the end! If you’re using an editor that shows line
+#' numbers, there should be (at least) two lines, where the second one is empty.
+#' Restart R for this to take effect. Call \code{gh_whoami()} to confirm
+#' success.
+#'
+#' To get complete information on the authenticated user, call
+#' \code{gh("/user")}.
+#'
+#' For token management via API (versus the browser), use the
+#' \href{https://developer.github.com/v3/oauth_authorizations/}{OAuth
+#' Authorizations API}. This API requires Basic Authentication using your
+#' username and password, not tokens, and is outside the scope of the \code{gh}
+#' package.
+#'
+#' @inheritParams gh
+#'
+#' @return A \code{gh_response} object, which is also a \code{list}.
+#' @export
+#'
+#' @examples
+#' \dontrun{
+#' gh_whoami()
+#'
+#' ## explicit token + use with GitHub Enterprise
+#' gh_whoami(.token = "8c70fd8419398999c9ac5bacf3192882193cadf2",
+#'           .api_url = "https://github.foobar.edu/api/v3")
+#' }
+gh_whoami <- function(.token = NULL, .api_url = NULL, .send_headers = NULL) {
+  .token <- .token %||% gh_token()
+  if (isTRUE(.token == "")) {
+    message("No personal access token (PAT) available.\n",
+            "Obtain a PAT from here:\n",
+            "https://github.com/settings/tokens\n",
+            "For more on what to do with the PAT, see ?gh_whoami.")
+    return(invisible(NULL))
+  }
+  res <- gh(endpoint = "/user", .token = .token,
+            .api_url = .api_url, .send_headers = .send_headers)
+  scopes <- attr(res, "response")[["x-oauth-scopes"]]
+  res <- res[c("name", "login", "html_url")]
+  res$scopes <- scopes
+  res$token <- hide_middle(.token)
+  ## 'gh_response' class has to be restored
+  class(res) <- c("gh_response", "list")
+  res
+}
+
+hide_middle <- function(x, n = 4) {
+  paste0(substr(x, start = 1, stop = n),
+         "...",
+         substr(x, start = nchar(x) - n + 1, stop = nchar(x)))
+}

R/package.R

@@ -34,7 +34,7 @@ NULL
 #'    If the method is not supplied, will use \code{.method}, which defaults
 #'    to \code{GET}.
 #' @param ... Name-value pairs giving API parameters. Will be matched
-#'   into \code{url} placeholders, send as query parameters in \code{GET}
+#'   into \code{url} placeholders, sent as query parameters in \code{GET}
 #'   requests, and in the JSON body of \code{POST} requests.
 #' @param .token Authentication token.
 #' @param .api_url Github API url (default: \url{https://api.github.com}).
@@ -67,6 +67,8 @@ NULL
 #' @importFrom jsonlite fromJSON toJSON
 #' @importFrom utils URLencode
 #' @export
+#' @seealso \code{\link{gh_whoami}()} for details on GitHub API token
+#'   management.
 #' @examples
 #' \dontrun{
 #' ## Repositories of a user, these are equivalent

R/pagination.R

@@ -57,7 +57,7 @@ gh_link <- function(gh_response, link) {
 #' @details
 #' Note that these are not always defined. E.g. if the first
 #' page was queried (the default), then there are no first and previous
-#' pages defined. If there is no next page, then there is nog
+#' pages defined. If there is no next page, then there is no
 #' next page defined, etc.
 #'
 #' If the requested page does not exist, an error is thrown.

appveyor.yml

@@ -12,6 +12,10 @@ install:
 
 # Adapt as necessary starting from here
 
+environment:
+  global:
+    GITHUB_TOKEN: ANYTHING_BUT_NULL
+
 build_script:
   - travis-tool.sh install_deps
 

tests/testthat/helper.R

@@ -12,7 +12,9 @@ if (file.exists("github-token.txt")) {
   Sys.setenv(DEBUGME = "httrmock")
   httrmock::start_recording()
   httrmock::start_replaying()
-
+  ms <- httrmock::mocking_status()
+  message("mocking status:\n",
+          paste(names(ms), ms, sep = ": ", collapse = "\n"))
 } else {
   httrmock::stop_recording()
   httrmock::start_replaying()

tests/testthat/httrmock/keys/objects/1b3bdfc20da2394badadab615ceed82c

@@ -0,0 +1 @@
+b9a62b3016e67bbab29cda2f3ec3457b

tests/testthat/httrmock/keys/objects/ebbdcbead1d79635fc42a966994ee813

@@ -0,0 +1 @@
+99a06080989bb5e278f39cf8c9035a26

tests/testthat/test-whoami.R

@@ -0,0 +1,29 @@
+context("whoami")
+
+test_that("whoami works in presence of PAT", {
+  ## being explicit re token because GITHUB_PAT > GITHUB_TOKEN in gh_token()
+  ## don't want developer's GITHUB_PAT to override gh-testing's GITHUB_TOKEN
+  res <- gh_whoami(Sys.getenv("GITHUB_TOKEN"))
+  expect_s3_class(res, "gh_response")
+  expect_identical(res[["login"]], "gh-testing")
+  expect_match(res[["scopes"]], "\\brepo\\b")
+  expect_match(res[["scopes"]], "\\buser\\b")
+})
+
+test_that("whoami works in absence of PAT", {
+  expect_message(res <- gh_whoami(.token = ""),
+                 "No personal access token \\(PAT\\) available.")
+  expect_null(res)
+})
+
+test_that("whoami errors with bad PAT", {
+  skip("re-activate when request matching sorted out (gaborcsardi/httrmock#3)")
+
+  e <- tryCatch(gh_whoami(.token = NA), error = identity)
+  expect_s3_class(e, "github_error")
+  expect_s3_class(e, "http_error_401")
+
+  e <- tryCatch(gh_whoami(.token = "blah"), error = identity)
+  expect_s3_class(e, "github_error")
+  expect_s3_class(e, "http_error_401")
+})