Rename to simple names

.Rbuildignore

@@ -10,3 +10,4 @@
 ^cran-comments\.md$
 ^CODE_OF_CONDUCT\.md$
 ^README$
+^CRAN-SUBMISSION$

CRAN-SUBMISSION

@@ -0,0 +1,3 @@
+Version: 0.1.0
+Date: 2024-02-26 18:33:26 UTC
+SHA: 0eba30fefa36068f06aed449fbd7841ab25054c7

NAMESPACE

@@ -1,10 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
-export(mm_auth)
-export(mm_define_gets)
-export(mm_get)
-export(mm_get_col_info)
-export(mm_get_criteria)
-export(mm_get_labels)
-export(mm_get_schema)
+export(mm_authorize)
+export(mm_data)
+export(mm_names)
 importFrom(lifecycle,deprecated)

R/authorize.R → R/auth.R

@@ -1,26 +1,24 @@
 #' Install Megamation credentials
 #'
-#' @description
-#' `mm_auth()` installs your credentials so that `megamation` functions
-#' that need them, like [mm_get()], can use them automatically.
+#' @description `mm_authorize()` installs your credentials so that `megamation`
+#'   functions that need them, like [mm_data()], can use them automatically.
 #'
-#' Specifically, it places your Megamation API key and base URL
-#' in your computer's `megamation` R package configuration files. Then,
-#' whenever the package is loaded, your credentials are available as environment
-#' variables.
+#'   Specifically, it places your Megamation API key and base URL in your
+#'   computer's `megamation` R package configuration files. Then, whenever the
+#'   package is loaded, your credentials are available as environment variables.
 #'
 #' @param key Single string of the Megamation API key.
 #' @param url Single string of the Megamation API base URL.
 #' @returns Writes `MEGAMATION_KEY` and `MEGAMATION_URL` environment variables.
 #' @export
 #' @examples
 #' \dontrun{
-#' mm_auth(
+#' mm_authorize(
 #'   key = "<YOUR-MEGAMATION_KEY>",
 #'   url = "<YOUR-MEGAMATION_URL>"
 #' )
 #' }
-mm_auth <- function(key, url) {
+mm_authorize <- function(key, url) {
   check_string(key)
   check_string(url)
   url <- check_url(url)

R/data.R

@@ -0,0 +1,61 @@
+#' Download data
+#'
+#' @description `mm_data()` downloads Megamation tables into R. It automatically
+#'
+#' 1. Creates and performs the necessary API GET request(s)
+#' 2. Extracts and combines the data from the API response(s)
+#' 3. Informs when no data is returned or when the API errors
+#'
+#' @inheritParams mm_req
+#' @param allfields If `TRUE`, return all fields currently available for the
+#'   endpoint.
+#' @returns A data frame of class [`tbl_df`][tibble::tbl_df-class] containing
+#'   the requested data.
+#' @export
+#' @examplesIf megamation:::has_creds()
+#' date <- seq.Date(as.Date("2023-01-01"), as.Date("2023-01-03"), by = "day")
+#' mm_data("timecard", date = date)
+mm_data <- function(endpoint, ..., allfields = TRUE) {
+  gets <- mm_list_get_reqs(endpoint, ..., allfields = allfields)
+
+  cli::cli_alert_info("Requesting...")
+
+  responses <- purrr::map(
+    gets |>
+      cli::cli_progress_along(format = "Fulfilling request {cli::pb_current}"),
+    \(x) mm_req_perform(gets[[x]])
+      )  |>
+    purrr::list_flatten()
+
+  errors <- responses |> httr2::resps_failures()
+  errors_occured <- !rlang::is_empty(errors)
+
+  successes <- responses |> httr2::resps_successes()
+  pages <- successes |> purrr::map(mm_resp_extract)
+
+  no_data_i <- pages |> purrr::map_lgl(is.null) |> which()
+
+  if (errors_occured || any(no_data_i)) {
+    cli::cli_alert_info(
+      c("NB: {length(errors) + length(no_data_i)}/{length(responses)}",
+        " requests returned errors or no data.")
+      )
+    for (error in errors) {
+      url <- error$request$url
+      msg <- error$message
+      cli::cli_h1("Errored")
+      glue::glue("{msg} \n {cli::style_bold('GET')} {url}") |>
+        cli::cli_alert_danger()
+    }
+
+    for (i in no_data_i) {
+      url <- successes[[i]]$request$url
+      cli::cli_h1("No Data Returned")
+      glue::glue("\n {cli::style_bold('GET')} {url}") |>
+        cli::cli_alert_danger()
+    }
+  }
+
+  data <- pages |> mm_pagebind()
+  remove_api_urls(data)
+}

R/env.R

@@ -1,6 +1,6 @@
 #' Get Megamation key
-#' @returns The string value of the `MEGAMATION_KEY` environment variable
-#' or an error if none exists.
+#' @returns The string value of the `MEGAMATION_KEY` environment variable or an
+#'   error if none exists.
 #' @keywords internal
 mm_key <- function() {
   key <- Sys.getenv("MEGAMATION_KEY")
@@ -15,9 +15,9 @@ mm_key <- function() {
   }
 }
 
-#' Get Megamaton URL
-#' @returns The string value of the `MEGAMATION_URL` environment variable
-#' or an error if none exists.
+#' Get Megamation URL
+#' @returns The string value of the `MEGAMATION_URL` environment variable or an
+#'   error if none exists.
 #' @keywords internal
 mm_url <- function() {
   url <- Sys.getenv("MEGAMATION_URL")
@@ -40,8 +40,8 @@ mm_url <- function() {
 
 #' Get testing key
 #'
-#' testing_key() uses the `MEGAMATION_KEY_HTTR2` environment
-#' variable to decrypt a secret.
+#' testing_key() uses the `MEGAMATION_KEY_HTTR2` environment variable to decrypt
+#' a secret.
 #' @returns A string of a decrypted key.
 #' @keywords internal
 testing_key <- function() {

R/error.R

@@ -4,8 +4,8 @@
 #' where Megamation's API includes informative error messages.
 #'
 #' @param resp An API response.
-#' @returns A string from the `detail` index of a named
-#' list (the parsed response).
+#' @returns A string from the `detail` index of a named list (the parsed
+#'   response).
 #' @keywords internal
 #' @examples
 #' fake_mm_resp <- httr2::response_json(

R/extract.R

@@ -1,12 +1,12 @@
 #' Extract data from Megamation API response
 #'
-#' `mm_resp_extract()` parses the raw bytes from an API response,
-#' and extracts data from the parsed object.
+#' `mm_resp_extract()` parses the raw bytes from an API response, and extracts
+#' data from the parsed object.
 #'
 #' @param resp An API response.
-#' @description The body of the response contains raw bytes.
-#' After converting these bytes to a string, encoding is done to resolve
-#' a UTF-8 issue from Megamation's side.
+#' @description The body of the response contains raw bytes. After converting
+#'   these bytes to a string, encoding is done to resolve a UTF-8 issue from
+#'   Megamation's side.
 #' @returns A data frame containing the endpoint data.
 #' @keywords internal
 #' @examples

R/list_gets.R

@@ -0,0 +1,66 @@
+#' List GET requests
+#'
+#' @description `mm_list_get_reqs()` returns the necessary GET request(s) for
+#'   fetching the supplied endpoint and parameters. Multiple GET requests are
+#'   sometimes needed for two reasons.
+#'
+#' One, Megamation does not support common ways of separating multiple values
+#'   for a field inside an HTTP URL. These ways include:
+#'
+#' * using a `,`, e.g. `?x=1,2`
+#' * using a `|`, e.g. `?x=1|2`
+#' * turning each element into its own parameter, e.g. `?x=1&x=2`
+#'
+#'   For Megamation, the first two ways will result in a 404 error. The last way
+#'   fetches data where x is both 1 and 2 (not 1 or 2). Hence
+#'   `mm_list_get_reqs()` defines separate GET requests for each value given to
+#'   a parameter.
+#'
+#'
+#' Two, the timecard endpoint is unique in that separate GET requests must be
+#'   made for separate years of data (e.g. 2022 vs 2023). This is also
+#'   automatically handled by `mm_list_get_reqs()`.
+#'
+#' @inheritParams mm_data
+#' @returns A list of GET requests of class `httr2_request`.
+#' @noRd
+#' @examplesIf megamation:::has_creds()
+#' date <- seq.Date(as.Date("2022-01-01"), as.Date("2023-01-31"), by = "day")
+#' megamation:::mm_list_get_reqs("timecard", date = date)
+mm_list_get_reqs <- function(endpoint, ..., allfields = TRUE) {
+  params <- format_params(endpoint, ...)
+  args <- tidyr::crossing(!!!params) |>
+    ## I() does not work here but we can hope
+    dplyr::mutate(
+      endpoint = endpoint,
+      dplyr::across(dplyr::everything(), I)
+    )
+
+  if (endpoint == "timecard" && "DATE" %in% names(params)) {
+    args <- add_tableyear(args)
+  }
+
+  requests <- args |>
+    purrr::pmap(mm_req) |>
+    purrr::list_flatten()
+
+  if (!allfields) {
+    return(requests)
+  }
+
+  requests |> purrr::map(\(req) httr2::req_url_query(req, ALLFIELDS = 1))
+
+}
+
+# Add the TABLEYEAR parameter which is required for past years of the "timecard"
+# endpoint
+add_tableyear <- function(df) {
+  DATE <- NULL
+  df |>
+    dplyr::mutate(
+      TABLEYEAR = DATE |>
+        stringi::stri_extract(regex = "\\d{4}") |>
+        ## Current year does not accept TABLEYEAR parameter
+        dplyr::na_if(Sys.Date() |> lubridate::year() |> as.character())
+    )
+}