gmailr 2.0.0

Changes around the OAuth client

• Set up an OAuth client
  is a new non-vignette article with detailed instructions for creating and
  configuring an OAuth client.

• gm_default_oauth_client() is a new helper that searches for the JSON file
  representing an OAuth client in a sequence of locations. The (file)path of
  least resistance is to place this file in the directory returned by
  rappdirs::user_data_dir("gmailr"). Another alternative is to record its
  filepath in the GMAILR_OAUTH_CLIENT environment variable. For backwards
  compatibility, the GMAILR_APP environment variable is still consulted, but
  generates a warning (#166).

• gm_auth() no longer checks for an OAuth client before calling
  gargle::token_fetch(). This allows other auth methods to work, which by and
  large don't need an OAuth client, such as gargle::credentials_byo_oauth2()
  (#160, #186).

• If gm_auth() fails to get a token and no OAuth client has been configured,
  it silently calls gm_auth_configure() to make one attempt at automatic
  client discovery. If an OAuth client is indeed discovered, gm_auth() tries
  one more time to get a token.

  Since the lack of an OAuth client undoubtedly remains the most common reason
  for gm_auth() to fail, its error message includes some specific content if
  no OAuth client has been configured.

Storing and deploying a token

• gm_token_write() + gm_token_read() is a new matched pair of functions that
  make it much easier to explicitly store a token obtained in an interactive
  session then reuse that token elsewhere, such in CI or in a deployed product
  (#190).

• The directory system.file("deployed-token-demo", package = "gmailr")
  contains a working demo of how to use gm_token_write() +
  gm_token_read() in a deployed Shiny app.

• vignette("deploy-a-token") is a new vignette describing how to capture a
  token interactively, for later use in a non-interactive setting.

Syncing up with gargle

Versions 1.3.0, 1.4.0, and 1.5.1 of gargle introduced some changes around OAuth and gmailr is syncing up that:

• gm_oauth_client() is a new function to replace the now-deprecated
  gm_oauth_app(). This is somewhat about a vocabulary change ("client" instead
  of "app"), but it's really connected to a more meaningful shift in gargle,
  which has a new appreciation for different OAuth client types (e.g.,
  "installed" vs. "web").
• gm_oauth_client() (and the function it's replacing, gm_oauth_app()) no
  longer error if there is no configured OAuth client.
• gm_auth_configure() has an updated signature:
  • The first argument is now named client, which is morally equivalent to the
    previous app, i.e. this is essentially a name change.
  • The key, secret, appname, and app arguments are deprecated.
  • Our strong recommendation is to use the path argument, either explicitly::

    gm_auth_configure(path = "path/to/my-oauth-client.json")

    or implicitly:

    gm_auth_configure()

    which works because of the new default:
    gm_auth_configure(path = gm_default_oauth_client()).

Other changes

• gm_auth(subject =) is a new argument that can be used with
  gm_auth(path =), i.e. when using a service account. The path and
  subject arguments are ultimately processed by
  gargle::credentials_service_account() and support the use of a service
  account to impersonate a regular user.

• gm_scopes() can now take a character vector of scopes, each of which can be
  an actual scope or a short alias, e.g., "gmail.readonly", which identifies a
  scope associated with the Gmail API. When called without arguments,
  gm_scopes() still returns a named vector of Gmail API-specific scopes, where
  the names are the associated short aliases.

• The deprecation process for legacy functions that lack the gm_ prefix has
  been advanced. The functions are still present, but throw an error directing
  the user to switch to the prefixed version.

  The unexported helper
  gmailr:::gm_convert_file(list.files(pattern = "[.]R$", recursive = TRUE))
  can be used to convert all R files in the current directory to the new names
  (#95).

• Legacy auth functions clear_token(), gmail_auth(), and use_secret_file()
  now throw an error.

• gmailr no longer Imports magrittr and no longer re-exports the magrittr pipe
  (%>%). gmailr is a very pipe-friendly package, so this was originally done
  for user convenience (#42).

  Since most users (those using R >= 4.1) now have access to the base pipe
  (|>), that is now what is shown in gmailr's documentation. Those using R <
  4.1 can still use gmailr with magrittr::%>%, but they will need to do
  library(magrittr) for themselves.

  Any gmailr examples that use the base pipe will no longer work on R < 4.1. On
  affected R versions, the examples are automatically converted to a regular
  section with a note that they might not work.