## ----include = FALSE----------------------------------------------------------
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

## ----setup--------------------------------------------------------------------
library(formr)

# So this vignette runs offline, API calls are replayed from pre-recorded
# responses (vcr cassettes shipped with the package). With a real server you
# would instead call formr_api_authenticate() with your own host/credentials.
.formr_vcr <- requireNamespace("vcr", quietly = TRUE) &&
  nzchar(system.file("extdata/vcr_cassettes", package = "formr"))

if (.formr_vcr) {
  vcr::vcr_configure(
    dir = system.file("extdata/vcr_cassettes", package = "formr"),
    filter_sensitive_data = list(
      "formr-client-id-redacted"     = "dummy_client_id",
      "formr-client-secret-redacted" = "dummy_client_secret",
      "formr-host-redacted"          = "api.localhost"
    )
  )
  vcr::use_cassette("formr_api_authenticate", {
    formr_api_authenticate(host = "http://api.localhost",
      client_id = "dummy_client_id", client_secret = "dummy_client_secret",
      verbose = FALSE)
  })
}

## ----install, eval = FALSE----------------------------------------------------
# # Not run: needs credentials / a live formr server.
# if (!requireNamespace("remotes")) install.packages("remotes")
# remotes::install_github("rubenarslan/formr")

## ----setup2, eval = FALSE-----------------------------------------------------
# library(formr)

## ----store_keys, eval = FALSE-------------------------------------------------
# # Not run: needs credentials / a live formr server.
# # Store your credentials once
# # This saves them securely in your OS credential store
# formr_store_keys(
#   host = "https://api.rforms.org",
#   client_id = "YOUR_CLIENT_ID",
#   client_secret = "YOUR_CLIENT_SECRET",
#   # Optional but recommended when you have more than one credential:
#   # pass the same string you used as the credential's label on the
#   # server. This lets you switch between credentials by name when you
#   # call formr_api_authenticate(account = "...").
#   account = "dashboard"
# )

## ----store_keys_classic, eval = FALSE-----------------------------------------
# # Not run: needs credentials / a live formr server.
# # Store your email/password under a shorthand name (e.g. "main_account")
# formr_store_keys("main_account")

## ----eval = FALSE-------------------------------------------------------------
# # Not run: authenticate with your own host/credentials.
# # Automatically finds your stored keys
# formr_api_authenticate(host = "https://api.rforms.org", account = "dashboard") # or your custom API-URL + account name!

## ----auth_local, eval = .formr_vcr--------------------------------------------
# After authentication, you can see which scopes the credential carries:
formr_api_session()$scope

## ----connect_classic, eval = FALSE--------------------------------------------
# # Not run: needs credentials / a live formr server.
# # Connect using the stored credentials
# formr_connect("main_account")

## ----auth_run, eval = FALSE---------------------------------------------------
# # Not run: needs credentials / a live formr server.
# # Inside a formr Run, simply call:
# formr_api_authenticate() # The package detects that it's running inside a Run and uses the temporary context provided by the server.

## ----push_pull, eval = FALSE--------------------------------------------------
# # Not run: needs credentials / a live formr server.
# # Download a project (surveys and files) to your local folder
# formr_api_pull_project("daily_diary")
# 
# # Upload changes back to the server
# formr_api_push_project("daily_diary")

## ----results, eval = .formr_vcr-----------------------------------------------
# Fetch and process
vcr::use_cassette("formr_api_results_fetch_single", {
  df <- formr_api_results("test-run", verbose = FALSE)
})
class(df)

## ----logout, eval = FALSE-----------------------------------------------------
# # Not run: revokes the live token on the server.
# formr_api_logout()