rcaspio: R Wrapper for Caspio REST API

#   ____________________________________________________________________________
#   Get Requests                                                            ####
#   These functions are convenience wrappers for caspio_get(resource)


##  ............................................................................
##  Applications                                                            ####

# GET /v2/applications Returns list of apps
#' Get list of applications
#'
#' @return A character vector with integration apps
#' @export
get_applications <- function() {
  resource <- "applications"
  caspio_get(resource)
}

# GET /v2/applications/{externalKey} Returns the app properties
#' Get a particular app's properties
#'
#' @return TODO
#' @export
get_application <- function(external_key) {
  # Add error handling
  resource <- paste0("applications/", external_key)
  caspio_get(resource)
}

# GET /v2/applications/{externalKey}/datapages Returns list of DataPages properties

# GET /v2/applications/{externalKey}/datapages/{appKey} Returns the DataPage properties

# GET /v2/applications/{externalKey}/datapages/{appKey}/deployment Returns the DataPage deploy code


##  ............................................................................
##  Tables                                                                  ####


# GET /v2/tables Returns the list of available tables
#' Get list of available tables
#'
#' @return A character vector with table names
#' @export
get_tables <- function() {
  resource <- "tables/"
  caspio_get(resource) %>% 
    .$Result
}

# GET /v2/tables/{tableName} Returns the description of the table
#' Get list of available tables
#'
#' @param table_name The name of the table(s), as a character string or vector
#' @return A tibble, with the table Name and any Notes on Caspio
#' @export
get_table <- function(table_name = get_tables()) {
  table_name %>% 
    purrr::map_df(function(tab){
      if(tab %!in% get_tables()) {
        paste0("'", tab, "'", " is not an available table.\n",
               "  Run get_tables() for a list of available tables.") %>% 
        stop()
      } 
      resource <- paste0("tables/", tab)
      caspio_get(resource) %>% 
        .$Result
    })
}

# GET /v2/tables/{tableName}/fields Returns the table definition
#' Get fields defined in a table
#' 
#' @param table_name The name of the table(s)
#' @return A tibble of fields in a given table, and their associated metadata
#' @export
get_fields <- function(table_name = get_tables()){
  table_name %>% 
    purrr::map_df(function(tab){
      if(tab %!in% get_tables()){
       paste0("'", tab, "'", " is not an available table.\n",
               "  Run get_tables() for a list of available tables.") %>% 
        stop()
      } 
      resource <- paste0("tables/", tab, "/fields")
      caspio_get(resource) %>%
        .$Result %>% 
        dplyr::mutate(Table = tab) %>% 
        dplyr::select(Table, dplyr::everything())
    })
}

# GET /v2/tables/{tableName}/fields/{fieldName} Returns the field definition
#' Get a field definition
#' 
#' @param table_name The name of the table
#' @param field_name The name of the field(s) 
#' @return A tibble of fields in a given table, and their associated metadata
#' @export
get_field <- function(table_name, field_name = NULL){
  # Store "valid" field names
  valid_fields <- get_fields(table_name) %>% 
    dplyr::pull(Name)
  # Request all fields if field_name unspecified
  if(is.null(field_name)){
    field_name <- valid_fields
  } else {
    # Throw error if field_name not valid
    if(field_name %!in% valid_fields){
      stop("'", field_name, "' is not an available field in the table ", 
           "'", table_name, "'")
    }
  }
  # Map over field names and request field definition
  field_name %>% 
    purrr::map_df(function(field) {
      valid_fields <- 
      resource <- paste0("tables/", table_name, "/", field)
      caspio_get(resource) %>% 
        .$Result %>% 
        dplyr::mutate(Table = table_name) %>% 
        dplyr::select(Table, dplyr::everything())
    })
}

# GET /v2/tables/{tableName}/passwordFields Returns a list of the table password fields
#' Get list of password fields in a table
#' 
#' @param table_name the name of the table
#' @return A character vector of password fields in a table
#' @export
get_password_fields <- function(table_name){
  table_name %>% 
    purrr::map(function(tab){
      if(tab %!in% get_tables()) {
        paste0("'", tab, "'", " is not an available table.\n",
               "  Run get_tables() for a list of available tables.") %>% 
        stop()
      }
      resource <- paste0("tables/", tab, "/passwordFields")
      password_fields <- caspio_get(resource) %>% 
        .$Result
      if(length(password_fields) > 0) {
        names(password_fields) <- rep(tab, len(password_fields))
      }
    })
}


# GET /v2/tables/{tableName}/records Returns records from the table
#' Get records from a specified table
#' 
#' @param table_name the name of the table
#' @param ... Optional, additional query parameters to pass to httr::GET
#' @return A tibble with records
#' @export
get_records <- function(table_name, ...){
  # Allow additional parameters to be passed into a query
  # TODO: integrate SQL query/limit/pagenumber/pagesize
  # Stop if table is not available
  if(table_name %!in% get_tables()) {
    paste0("'", tab, "'", " is not an available table.\n",
               "  Run get_tables() for a list of available tables.") %>% 
      stop()
  }
  # List for query parameters
  query_list <- list(...)

  # If no query parameters, iteratively pull all records
  if(length(query_list) == 0) {
    # To be populated with record data
    records <- tibble::tibble()
    # Initial values
    page_number <- 1
    page_size <- 25
    page_full <- TRUE
    while(page_full){
      # Request the record page
      resource <- paste0(
        "tables/", table_name, 
        "/records", "?",
        "pageNumber=", page_number, "&",
        "pageSize=", page_size
      )
      to_append <- caspio_get(resource) %>% 
        .$Result
      records <- rbind(records, to_append)
      # Update page_number for next iteration
      page_number <- page_number + 1
      # Check number of records returned, and update page_full if incomplete
      if(nrow(to_append) < page_size) {
        page_full <- FALSE
      }
    }
  } else {
    # Concatenate params into query string, append to `resource` url
  }
  tibble::as_tibble(records) %>% 
    return()
}


##  ............................................................................
##  Views                                                                   ####

# GET /v2/views Returns the list of views

# GET /v2/views/{viewName} Returns the description of a view

# GET /v2/views/{viewName}/records Returns records from the view



##  ............................................................................
##  Files                                                                   ####

# GET /v2/files Returns the specified file metadata or the list of files and folders depending on externalKey

# GET /v2/files/{externalKey} Returns a file content as an attachment


##  ............................................................................
##  Tasks                                                                   ####

# GET /v2/tasks Returns the list of scheduled tasks

# GET /v2/tasks/{externalKey} Returns properties of the task