## ----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 = .formr_vcr--------------------------------------------------------
# List all runs and their status
vcr::use_cassette("formr_api_runs_list", {
  runs <- formr_api_runs()
})

# Quickly check which runs are currently active/public
subset(runs, public == TRUE)

## ----eval = .formr_vcr--------------------------------------------------------
# Create a new run named "test-run"
vcr::use_cassette("formr_api_runs_create", {
  formr_api_create_run("test-run", verbose = FALSE)
})

## ----eval = FALSE-------------------------------------------------------------
# # Not run: needs a live formr server.
# # 1. View current settings
# settings <- formr_api_run_settings("pilot-study-v1")
# 
# # 2. Update settings: Lock the run and make it public
# formr_api_run_settings("pilot-study-v1", settings = list(
#   locked = TRUE,     # Prevent structure changes
#   public = 2,      # Allow participants to access via Link
#   expiresOn = "2026-12-31"
#   # Set Data Expiration Date (required to make your Run public)
# ))

## ----eval = .formr_vcr--------------------------------------------------------
# Inspect structure in R
vcr::use_cassette("formr_api_run_structure_import", {
  struct <- formr_api_run_structure("test-run")
})
print(struct)

## ----eval = FALSE-------------------------------------------------------------
# # Not run: writes a file and needs a live server.
# # Save to file (Backup)
# formr_api_run_structure("pilot-study-v1", file = "pilot_v1_structure.json")

## ----eval = FALSE-------------------------------------------------------------
# # Not run: needs a live formr server.
# # Overwrite the run's structure with a local JSON file
# formr_api_run_structure("pilot-study-v1", structure_json_path = "pilot_v1_structure.json")

## ----eval = .formr_vcr--------------------------------------------------------
# Delete a run (prompts for confirmation by default)
vcr::use_cassette("formr_api_runs_delete", {
  formr_api_delete_run("test-run", prompt = FALSE)
})

## ----eval = FALSE-------------------------------------------------------------
# # Force delete without confirmation (for automated scripts)
# formr_api_delete_run("pilot-study-v1", prompt = FALSE)