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)

Build long-format mapping of ForceDecks test attributes

Description

Given a list of test records (from parsed JSON), this returns one row per test-attribute combination, with a stable set of columns.

Usage

.build_test_attributes_long(records)

Arguments

Details

Only attributes with at least one non-blank field are included. Tests with no attributes (or only blank attributes) do not appear in the result.

Value

data.frame with columns:

• testId

• attributeTypeId

• attributeTypeName

• attributeValueId

• attributeValueName

Get categories for a tenant

Description

Queries the External Tenants API /categories endpoint.

Usage

.get_categories()

Value

A data frame with category meta data.

Get groups for a tenant

Description

Queries the External Tenants API /groups endpoint.

Usage

.get_groups()

Value

A data frame with group meta data.

Get profile group memberships

Description

For a vector of profileIds, query the Profiles API for each profile and extract its groupIds.

Usage

.get_profile_group_ids(profile_ids)

Arguments

Value

A data frame with columns profileId and groupId (long format).

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)

Build default VALD API endpoints for a region

Description

Internal helper used to derive endpoint URLs from a region code.

Usage

.vald_default_endpoints(region)

Default export directory (Downloads/VALD_Exports)

Description

Internal helper to resolve the user's Downloads folder in a cross-platform friendly way, and append a VALD_Exports subfolder. Falls back to a temp directory if needed, with informative messages.

Usage

.vald_default_export_dir()

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)

Export ForceDecks data for dashboards

Description

Queries the ForceDecks API, joins trials/tests/profiles/result definitions, and writes a CSV file to the user's Downloads/VALD_Exports folder (by default).

Usage

export_forcedecks_csv(export_dir = NULL)

Arguments

Details

This export is ForceDecks-specific and uses the stored start date from get_start_date(), which is automatically updated by the ForceDecks data retrieval functions.

Value

Invisibly, the full path to the created CSV file.

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, include_attributes = FALSE)

Arguments

Value

A named list with data frames: profiles, result_definitions, tests, and trials. If include_attributes = TRUE, the list also contains test_attributes.

Examples

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

# Fetch all data including test attributes mapping
data_with_attrs <- get_forcedecks_data(include_attributes = TRUE)
View(data_with_attrs$test_attributes)

## 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,
  include_attributes = FALSE
)

Arguments

Value

If include_attributes = FALSE, a data frame containing ForceDecks test results matching the optional filters. If no tests are found, returns an empty data frame. If include_attributes = TRUE, a list with elements tests and attributes. 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, include_attributes = FALSE)

Arguments

Value

Either a data frame containing ForceDecks test-level data, or a list with components tests and attributes if include_attributes = TRUE.

Examples

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

# Fetch tests plus attributes mapping
res <- get_forcedecks_tests_only(include_attributes = TRUE)
tests <- res$tests
attrs <- res$attributes

## 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, include_attributes = FALSE)

Arguments

Value

A named list with data frames: tests and trials. If include_attributes = TRUE, the list also contains test_attributes.

Examples

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

# Fetch tests, trials, and test attributes mapping
session2 <- get_forcedecks_tests_trials(include_attributes = TRUE)
View(session2$test_attributes)

## 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 profile group and category mappings

Description

Returns a long-format data frame of profile–category–group relationships. Each row represents a single combination of:

• profileId

• categoryId / categoryName (may be blank for legacy profiles)

• groupId / groupName (may be blank for legacy profiles)

Usage

get_profiles_groups_categories()

Details

Legacy profiles without groups or categories are still included, with blank group/category fields.

Internal function – use the exported wrapper(s) instead.

Value

A data frame with columns:

• profileId

• categoryId

• categoryName

• groupId

• groupName

Get profile–group–category mappings

Description

Wrapper around get_profiles_groups_categories() to retrieve the long-format mapping of profiles to their groups and categories.

Usage

get_profiles_groups_categories_mapping()

Details

Intended for use when you want a relational view of profile metadata rather than the one-row-per-profile structure returned by get_profiles().

Value

A data frame with one row per profile–group–category combination, containing the columns:

• profileId

• categoryId

• categoryName

• groupId

• groupName

Returned invisibly.

Examples

## Not run: 
# Fetch profile–group–category mappings for the current tenant
mappings <- get_profiles_groups_categories_mapping()
head(mappings)

## End(Not run)

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

Details

Also ensures that API endpoints are kept up to date for the current package version (e.g. when new endpoints are added), and persists any repaired endpoint configuration back to disk (non-sensitive fields only).

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.