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.

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.

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.

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.

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.

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.

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 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.

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.

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.