## ----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)
  })
}

## ----eval = FALSE-------------------------------------------------------------
# # Not run: needs a live formr server.
# # List all active sessions (participants currently in the study)
# active_users <- formr_api_sessions("my-run-name", active = TRUE)
# 
# # List all test sessions (e.g., generated by you)
# test_users <- formr_api_sessions("my-run-name", testing = TRUE)

## ----eval = FALSE-------------------------------------------------------------
# # Not run: needs a live formr server.
# # Get sessions 101-200
# sessions_page <- formr_api_sessions("my-run-name", limit = 100, offset = 100)

## ----eval = FALSE-------------------------------------------------------------
# # Not run: needs a live formr server.
# # Inspect a specific user
# user_status <- formr_api_sessions("my-run-name", session_codes = "USER_CODE_123")
# dplyr::glimpse(user_status)

## ----eval = .formr_vcr--------------------------------------------------------
# Create a random session code for testing
vcr::use_cassette("formr_api_create_session_basic", {
  new_sessions <- formr_api_create_session("test-run", testing = TRUE, verbose = FALSE)
})
new_sessions$count_created

## ----eval = FALSE-------------------------------------------------------------
# # Not run: needs a live formr server.
# # Create a session with a specific code (e.g., for a specific ID)
# # Please be sure that your session codes are in an allowed format on your server.
# formr_api_create_session("my-run-name", codes = c("LAB_001", "LAB_002"))

## ----eval = FALSE-------------------------------------------------------------
# # Not run: needs a live formr server.
# # Move user to position 10 (e.g., the next survey)
# formr_api_session_action("my-run-name",
#                      session_codes = "STUCK_USER_CODE",
#                      action = "move_to_position",
#                      position = 10)

## ----eval = FALSE-------------------------------------------------------------
# # Not run: needs a live formr server.
# # Mark a real session as a test session
# formr_api_session_action("my-run-name",
#                      session_codes = "REAL_USER_CODE",
#                      action = "toggle_testing")

## ----eval = FALSE-------------------------------------------------------------
# # Not run: needs a live formr server.
# # End a session
# formr_api_session_action("my-run-name",
#                      session_codes = "WITHDRAWN_USER_Code",
#                      action = "end_external")