Build a ForceFrame test data frame

Description

Internal helper to convert a list of ForceFrame test records into a tidy data.frame. For character columns, NULL values are replaced with an empty string ("") to ensure consistent downstream handling.

Usage

.build_forceframe_df(records)

Arguments

Details

Special handling is applied for the identifier column: some ForceFrame API endpoints return this as profileId, while others return it as athleteId. This function will populate the profileId column by taking the first non-empty value from profileId or athleteId, in that order.

Value

A data.frame where each row corresponds to a ForceFrame test record. Internal function (not designed to be used directly by end users)

Build a NordBord test data frame

Description

Internal helper to convert a list of NordBord test records into a tidy data.frame. For character columns, NULL values are replaced with an empty string ("") to ensure consistent downstream handling.

Usage

.build_nordbord_df(records)

Arguments

Details

Special handling is applied for the identifier column: some NordBord API endpoints return this as profileId, while others return it as athleteId. This function will populate the athleteId column by taking the first non-empty value from athleteId or profileId, in that order.

Value

A data.frame with one row per NordBord test record. Internal function (not designed to be used directly by end users)

Package attach hook for VALD API credentials

Description

.onAttach() displays credential load status messages to the user.

Usage

.onAttach(libname, pkgname)

Arguments

Package load hook for VALD API credentials

Description

.onLoad() initialises the internal package environment and attempts to load previously saved VALD API credentials and configuration.

Usage

.onLoad(libname, pkgname)

Arguments

Details

If a configuration file exists, this function tries to load the stored credentials. It defers messaging until .onAttach() to comply with CRAN policies.

Internal helper function to retry reading a key from the system keyring. This handles potential intermittent delays after writing to the keyring.

Description

Internal helper function to retry reading a key from the system keyring. This handles potential intermittent delays after writing to the keyring.

Usage

.retry_key_get(service, username, retries = 5, delay = 0.5)

Arguments

Value

Character scalar. The retrieved credential value. Will throw an error if unable to retrieve a valid, non-blank value after all retries.

Safely extract a field from a list of lists

Description

Internal helper function used to extract a specified field from a list of records. If a field value is NULL, it is replaced with an empty string ("").

Usage

.safe_extract(x, field)

Arguments

Value

A character vector containing the extracted values, with NULLs replaced by "". Internal function (not designed to be used directly by end users)

Safely extract the first non-empty field from a list of lists

Description

Internal helper function used to extract the first non-empty value from a list of fields, in order, from a list of records. If all fields are NULL or empty strings, returns "".

Usage

.safe_extract_first(x, fields)

Arguments

Value

A character vector containing the extracted values, with NULLs replaced by "". Internal function (not designed to be used directly by end users)

Safely extract a single value

Description

Internal helper function used to safely retrieve a single value from an object. If the value is NULL, it is replaced with an empty string ("").

Usage

.safe_value(x)

Arguments

Value

The original value, or "" if NULL. Internal function (not designed to be used directly by end users)

Validate a single GUID test ID

Description

Internal helper to validate that exactly one non-empty, non-NA, string-based GUID has been supplied.

Usage

.validate_single_guid(..., arg_name = "`test_id`")

Arguments

Value

A single validated test ID string. Internal function (not designed to be used directly by end users)

Authenticate and retrieve a valid access token

Description

Ensures a valid access token is available based on stored credentials. Also validates required tenant ID and token presence for subsequent function calls.

Usage

authenticate()

Value

A character vector of length 1 (a single string) representing a valid access token. Returned invisibly and used internally for authentication. Internal function (not designed to be used directly by end users)

Get or refresh VALD access token

Description

Retrieves a cached access token from disk if valid, otherwise fetches a new one.

Usage

get_access_token(config = NULL, verbose = TRUE)

Arguments

Value

(Invisibly) a character vector of length 1 containing the bearer token used for authenticating API requests. Internal function (not designed to be used directly by end users)

Retrieve stored VALD configuration

Description

Returns the configuration list previously set by set_credentials(). If credentials have not been set, this function will raise an error.

Usage

get_config(safe = TRUE, quiet = FALSE)

Arguments

Value

A named list containing the stored VALD configuration values for the current user. Sensitive values are redacted when printed with safe = TRUE. Returned invisibly.

Run full initial data fetch from the VALD ForceDecks API and External Profiles API

Description

This function is intended for first-time use or a full refresh of all datasets. It retrieves profiles, result definitions, tests (from a specified start date), and trials.

Usage

get_forcedecks_data(start_date = NULL)

Arguments

Value

A named list with data frames: profiles, result_definitions, tests, and trials. Each element contains the respective dataset fetched from the ForceDecks API.

Examples

## Not run: 
# Fetch all data (profiles, results, tests, trials)
data <- get_forcedecks_data()
View(data$profiles)

## End(Not run)

Get ForceDecks result definitions

Description

Retrieves all available result definitions from the ForceDecks API.

Usage

get_forcedecks_result_definitions()

Value

A data frame where each row corresponds to a ForceDecks result definition retrieved from the API. Returned invisibly. Internal function (not designed to be used directly by end users)

Get only ForceDecks result definitions

Description

Wrapper around get_forcedecks_result_definitions() to refresh result definitions. Typically called infrequently unless definitions are known to have changed.

Usage

get_forcedecks_result_definitions_only()

Value

A data frame where each row corresponds to a ForceDecks result definition retrieved from the API. Returned invisibly.

Examples

## Not run: 
# Fetch result definitions
results <- get_forcedecks_result_definitions_only()
View(results)

## End(Not run)

Get ForceDecks tests

Description

Retrieves ForceDecks test data with optional filtering by start date and profile ID.

Usage

get_forcedecks_tests(start_date = NULL, profile_id = NULL)

Arguments

Value

A data frame containing ForceDecks test results matching the optional filters. If no tests are found, returns an empty data frame. Returned invisibly. Internal function (not designed to be used directly by end users)

Get only ForceDecks test data

Description

Wrapper around get_forcedecks_tests() if the user only wants test-level data without trials.

Usage

get_forcedecks_tests_only(start_date = NULL)

Arguments

Value

A data frame containing ForceDecks test-level data.

Examples

## Not run: 
# Fetch only tests
tests <- get_forcedecks_tests_only()
View(tests)

## End(Not run)

Run a standard session to get new ForceDecks tests and trials only

Description

Use this when profiles and result definitions have already been downloaded previously.

Usage

get_forcedecks_tests_trials(start_date = NULL)

Arguments

Value

A named list with two data frames: tests and trials. These contain newly retrieved ForceDecks tests and their associated trial results.

Examples

## Not run: 
# Fetch tests and trials only
session <- get_forcedecks_tests_trials()
View(session$tests)
View(session$trials)

## End(Not run)

Get trial results for a set of ForceDecks tests

Description

Retrieves and flattens trial-level result data for each test provided.

Usage

get_forcedecks_trials(tests_df)

Arguments

Value

A data frame containing flattened trial-level results for the supplied tests. If no trial results are found, returns an empty data frame. Internal function (not designed to be used directly by end users)

Get trials for an existing test data frame

Description

Useful for re-running or extending analysis without re-downloading tests.

Usage

get_forcedecks_trials_only(tests_df)

Arguments

Value

A data frame containing trial-level results corresponding to the input tests.

Examples

## Not run: 
# Fetch trials based on existing tests
tests <- get_forcedecks_tests_only()
trials <- get_forcedecks_trials_only(tests)
View(trials)

## End(Not run)

Get ForceFrame test data

Description

Wrapper around get_forceframe_tests() that also calls get_profiles() to ensure profile data is available before retrieving ForceFrame test data. Intended for use when you want to fetch Profiles information as well as ForceFrame tests from the API.

Usage

get_forceframe_data(start_date = NULL, profile_id = NULL)

Arguments

Value

A data frame containing Profiles information and a data frame containing ForceFrame test data.

Examples

## Not run: 
# Fetch all recent ForceFrame tests along with Profiles information
tests <- get_forceframe_data()
View(tests)

# Fetch ForceFrame tests for a specific profile
get_forceframe_data(profile_id = "abc123")

## End(Not run)

Get a single ForceFrame test by ID

Description

Wrapper around get_forceframe_tests_by_id() to retrieve a specific ForceFrame test. Intended for use when you want to fetch a single ForceFrame test record.

Usage

get_forceframe_test_by_id(test_id)

Arguments

Value

A data frame with one row corresponding to the requested ForceFrame test. Returned invisibly.

Examples

## Not run: 
# Fetch a ForceFrame test by ID
test <- get_forceframe_test_by_id("abcd1234-ab12-cd34-ef56-abcdef123456")
View(test)

## End(Not run)

Get ForceFrame Tests

Description

Fetches ForceFrame test records modified since a given start date. Supports automatic pagination and updates the persistent start_date after each call. Returns a data frame of test records, with null values replaced by blank strings ("").

Usage

get_forceframe_tests(start_date = NULL, profile_id = NULL)

Arguments

Value

A data frame containing ForceFrame test results matching the optional filters. If no tests are found, returns an empty data frame. Returned invisibly. Internal function (not designed to be used directly by end users)

Get a single ForceFrame test by ID

Description

Calls the ForceFrame API endpoint ⁠/tests/{testId}⁠ to retrieve one test record.

Usage

get_forceframe_tests_by_id(...)

Arguments

Value

A data frame containing the test details, or an empty data frame if not found. Internal function (not designed to be used directly by end users)

Get only ForceFrame test data

Description

Wrapper around get_forceframe_tests() to retrieve ForceFrame test data. Intended for use when you want to fetch ForceFrame tests.

Usage

get_forceframe_tests_only(start_date = NULL, profile_id = NULL)

Arguments

Value

A data frame where each row corresponds to a ForceFrame test retrieved from the API. Returned invisibly.

Examples

## Not run: 
# Fetch all recent ForceFrame tests
tests <- get_forceframe_tests_only()
View(tests)

# Fetch ForceFrame tests for a specific profile
get_forceframe_tests_only(profile_id = "abcd1234-ab12-cd34-ef56-abcdef123456")

## End(Not run)

Get NordBord test data

Description

Wrapper around get_nordbord_tests() that also calls get_profiles() to ensure profile data is available before retrieving NordBord test data. Intended for use when you want to fetch Profiles information as well as NordBord tests from the API.

Usage

get_nordbord_data(start_date = NULL, profile_id = NULL)

Arguments

Value

A data frame containing Profiles information and a data frame containing NordBord test data.

Examples

## Not run: 
# Fetch all recent NordBord tests along with Profiles information
tests <- get_nordbord_data()
View(tests)

# Fetch NordBord tests for a specific profile
get_nordbord_data(profile_id = "abcd1234-ab12-cd34-ef56-abcdef123456")

## End(Not run)

Get a single NordBord test by ID

Description

Wrapper around get_nordbord_tests_by_id() to retrieve a specific NordBord test. Intended for use when you want to fetch a single NordBord test record.

Usage

get_nordbord_test_by_id(test_id)

Arguments

Value

A data frame with one row corresponding to the requested NordBord test. Returned invisibly.

Examples

## Not run: 
# Fetch a NordBord test by ID
test <- get_nordbord_test_by_id("abcd1234-ab12-cd34-ef56-abcdef123456")
View(test)

## End(Not run)

Get NordBord Tests

Description

Retrieves all NordBord test data modified since a given start date. Automatically paginates through results using modifiedFromUtc, and safely detects infinite loops using the last seen test ID.

Usage

get_nordbord_tests(start_date = NULL, profile_id = NULL)

Arguments

Value

A data frame containing NordBord test results matching the optional filters. If no tests are found, returns an empty data frame. Returned invisibly. Internal function (not designed to be used directly by end users)

Get a single NordBord test by ID

Description

Calls the NordBord API endpoint ⁠/tests/{testId}⁠ to retrieve one test record.

Usage

get_nordbord_tests_by_id(...)

Arguments

Value

A data frame containing the test details, or an empty data frame if not found. Internal function (not designed to be used directly by end users)

Get only NordBord test data

Description

Wrapper around get_nordbord_tests() to retrieve NordBord test data. Intended for use when you want to fetch NordBord tests.

Usage

get_nordbord_tests_only(start_date = NULL, profile_id = NULL)

Arguments

Value

A data frame where each row corresponds to a NordBord test retrieved from the API. Returned invisibly.

Examples

## Not run: 
# Fetch all recent NordBord tests
tests <- get_nordbord_tests_only()
View(tests)

# Fetch NordBord tests for a specific profile
get_nordbord_tests_only(profile_id = "abcd1234-ab12-cd34-ef56-abcdef123456")

## End(Not run)

Get VALD profiles

Description

Queries the External Profiles API and returns a data frame of VALD profiles.

Usage

get_profiles()

Value

A data frame containing VALD profiles information for the stored tenant_id. If no profiles are found, the function raises an error. Internal function (not designed to be used directly by end users)

Get only VALD profiles

Description

Wrapper around get_profiles() to retrieve VALD profiles. Useful if profile data needs to be refreshed independently.

Usage

get_profiles_only()

Value

A data frame containing VALD profiles information for the stored tenant_id.

Examples

## Not run: 
# Fetch profiles
profiles <- get_profiles_only()
View(profiles)

## End(Not run)

Retrieve the start date from config

Description

Returns the saved start date string from the config file.

Usage

get_start_date()

Value

A character scalar containing the start date string in ISO 8601 format previously saved to configuration.

Check if JWT access token is expired

Description

Check if JWT access token is expired

Usage

is_token_valid(token)

Arguments

Value

A logical scalar (TRUE or FALSE) indicating whether the provided JWT access token is still valid based on its expiry timestamp. Internal function (not designed to be used directly by end users)

Load Stored VALD API Credentials and Configuration (with retry logic)

Description

Loads the saved VALD API configuration from the user's config file and retrieves sensitive credentials securely from the system keyring.

Usage

load_credentials(verbose = TRUE)

Arguments

Value

Invisibly returns TRUE if credentials and configuration were loaded successfully, FALSE otherwise.

Set and Save VALD API Credentials

Description

Securely stores VALD API credentials in the system keyring and saves non-sensitive configuration to a JSON config file in the user's home directory for reuse across sessions.

Usage

set_credentials(client_id, client_secret, tenant_id, region)

Arguments

Details

Sensitive values (client ID and secret) are never written to disk and are retrieved securely from the keyring when needed.

Value

Invisibly returns TRUE if credentials and configuration were saved successfully.

Set and persist the start date

Description

Saves the provided ISO 8601 start date to the config file.

Usage

set_start_date(start_date)

Arguments

Value

A logical scalar (TRUE), returned invisibly, indicating that the start date was saved and persisted successfully.