Merge pull request #45 from MangoTheCat/develop

release ready merge develop to main

.Rbuildignore

@@ -1,2 +1,10 @@
+^renv$
+^renv\.lock$
 ^.*\.Rproj$
 ^\.Rproj\.user$
+^\.github$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$
+^README\.Rmd$
+^LICENSE\.md$

.Rprofile

@@ -0,0 +1 @@
+source("renv/activate.R")

.github/.gitignore

@@ -0,0 +1 @@
+*.html

.github/workflows/R-CMD-check.yaml

@@ -0,0 +1,28 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+    branches: [main, master, develop]
+
+name: R-CMD-check
+
+jobs:
+  R-CMD-check:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      R_KEEP_PKG_SOURCE: yes
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: r-lib/actions/setup-r@v1
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v1
+        with:
+          extra-packages: rcmdcheck
+
+      - uses: r-lib/actions/check-r-package@v1

.github/workflows/pkgdown.yaml

@@ -0,0 +1,35 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master, develop]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: pkgdown
+
+jobs:
+  pkgdown:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: r-lib/actions/setup-pandoc@v1
+
+      - uses: r-lib/actions/setup-r@v1
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v1
+        with:
+          extra-packages: pkgdown
+          needs: website
+
+      - name: Deploy package
+        run: |
+          git config --local user.name "$GITHUB_ACTOR"
+          git config --local user.email "$GITHUB_ACTOR@users.noreply.github.com"
+          Rscript -e 'pkgdown::deploy_to_branch(new_process = FALSE)'

.github/workflows/test-coverage.yaml

@@ -0,0 +1,30 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+    branches: [main, master, develop]
+
+name: test-coverage
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: r-lib/actions/setup-r@v1
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v1
+        with:
+          extra-packages: covr, testthat
+
+      - name: Test coverage
+        run: covr::codecov()
+        shell: Rscript {0}

.gitignore

@@ -2,3 +2,4 @@
 .Rhistory
 .RData
 .Ruserdata
+docs

DESCRIPTION

@@ -1,22 +1,43 @@
 Package: bambooHR
 Type: Package
-Title: An R wrapper to the BambooHR API
+Title: A Wrapper to the 'BambooHR' API
 Version: 0.1.0
-Authors@R:
+Authors@R: 
     c(
     person("Tom", "Bowling", , "tom.bowling@ascent.io", role = c("aut", "cre")),
     person("Harry", "Alexander", , "harry.alexander@ascent.io", role = "aut"),
     person("Tim", "Fry", , "tim.fry@ascent.io", role = "aut"),
-    person("Mark", "Druffel", , "mdruffel@propellerpdx.com", role = "aut")
+    person("Andrew", "Little", role = "ctb"),
+    person("Mark", "Druffel", , "mdruffel@propellerpdx.com", role = "ctb"))
 Maintainer: Tom Bowling <tom.bowling@ascent.io>
-Description: Enables a user to consume the BambooHR API endpoints using R.
+Description: Enables a user to consume the 'BambooHR' API endpoints using R. The
+  actual URL of the API will depend on your company domain, and will be handled
+  by the package automatically once you setup the config file. The API documentation
+  can be found here <https://documentation.bamboohr.com/docs>.
 Depends: R (>= 4.0.0)
-Imports:
+Imports: 
     rlang,
     glue,
     httr,
-    curl
+    curl,
+    jsonlite,
+    magrittr,
+    dplyr,
+    purrr,
+    tibble,
+    tidyr,
+    lubridate,
+    testthat,
+    janitor,
+    stringr,
+    cli,
+    withr,
+    fs
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
 RoxygenNote: 7.1.2
+URL: https://mangothecat.github.io/bambooHR/
+BugReports: https://github.com/MangoTheCat/bambooHR/issues
+Suggests: httptest
+Config/testthat/edition: 3

NAMESPACE

@@ -1 +1,15 @@
-exportPattern("^[[:alpha:]]+")
+# Generated by roxygen2: do not edit by hand
+
+export("%>%")
+export(build_url)
+export(config_setup)
+export(get_employee)
+export(get_meta)
+export(get_table)
+export(get_timeoff_policies)
+export(get_timeoff_requests)
+export(get_timeoff_types)
+export(get_whos_out)
+export(use_config)
+importFrom(magrittr,"%>%")
+importFrom(rlang,.data)

R/bambooHR-package.R

@@ -0,0 +1,7 @@
+#' @keywords internal
+"_PACKAGE"
+
+## usethis namespace: start
+#' @importFrom magrittr %>%
+## usethis namespace: end
+NULL

R/build_url.r

@@ -1,50 +1,30 @@
 #' @title Build URL Endpoints with Company Domain and API Version
 #'
-#' @description  fill in
+#' @description  Used to generate the base API request URL. URLs will start with "https://api.bamboohr.com/api/gateway.php/{company_domain}" which forms the base URL where a query string can then be appended to make the full request URL.
 #'
-#' @param company_domain  tbd
-#' @param api_version tbd
-#' @param base_url tbd
+#' @param company_domain  The subdomain used to access BambooHR. If you access BambooHR at https://mycompany.bamboohr.com, then the company_domain is "mycompany".
+#' Default value is obtained from \code{options("bambooHR.company_name")}. This can also be set in the config file using \code{config_setup("api key", "company_domain")}.
+#' @param api_version Version of API to use to make request. Default is "v1".
+#' @param base_url URL to BambooHR API. Default is "https://api.bamboohr.com/api/gateway.php".
 #'
-#' @return text
+#' @return character vector of URL with API version and company domain to give the base URL for API requests.
 #'
-#' @examples
+#' @export
 #'
-#'
-#' @author Mark Druffel, \email{mdruffel@propellerpdx.com}
-
-build_url <- function(company_domain, api_version, base_url){
-  if(!rlang::is_null(base_url)){
-    base_url <- base_url
-  } else{
-    base_url <- rlang::missing_arg()
-  }
-  if(!rlang::is_null(api_version)){
-    api_version <- api_version
-  } else{
-    api_version <- rlang::missing_arg()
+build_url <- function(company_domain = .get_company_name(),
+                      api_version = "v1",
+                      base_url = "https://api.bamboohr.com/api/gateway.php") {
+  if (is.null(company_domain)) {
+    stop("Please enter company_domain or set a default value using `config_setup()`.")
   }
-  if(!rlang::is_null(company_domain)){
-    company_domain <- company_domain
-  } else{
-    company_domain <- rlang::missing_arg()
-  }
-  base_url <- get_base_url(base_url)
-  api_version <- get_api_version(api_version)
-  company_domain <- get_company_domain(company_domain)
+
+  stopifnot(
+    is.character(company_domain),
+    is.character(api_version),
+    is.character(base_url)
+  )
+
   url <- glue::glue("{base_url}/{company_domain}/{api_version}")
   return(url)
 }
 
-get_base_url <- function(base_url){
-  base_url <- rlang::maybe_missing(base_url, default = "https://api.bamboohr.com/api/gateway.php")
-  return(base_url)
-}
-get_api_version <- function(api_version){
-  api_version <- rlang::maybe_missing(api_version, default = "v1")
-  return(api_version)
-}
-get_company_domain <- function(company_domain){
-  company_domain <- rlang::maybe_missing(company_domain, default = "propellerpdx")
-  return(company_domain)
-}

R/date_utils.R

@@ -1,16 +1,58 @@
-#' @title Coerce input date parameters to ISO 8601 format for Bamboo HR REST API
+#' @title Check Date Format
 #'
-#' @examples
-#' as_ISO8601_character("2020-09-01")
-#' as_ISO8601_character("2020-09-01 00:00:00.001")
+#' @description Functions to check date and datetime formats
+#' @name date_formats
+NULL
+
+#' @describeIn date_formats Check format is YYYY-MM-DD
+#' @keywords internal
+is_ymd <- function(date = NULL) {
+  check <- grepl("^[1-9]{1}[0-9]{3}-[0-1]{1}[0-9]{1}-[0-3]{1}[0-9]{1}$",
+                 trimws(date))
+  return(check)
+}
+
+#' @describeIn date_formats Check format is YYYY-MM-DD HH:MM:SS
+#' @keywords internal
+is_ymd_hms <- function(date = NULL){
+  check <- grepl("^[1-9]{1}[0-9]{3}-[0-1]{1}[0-9]{1}-[0-3]{1}[0-9]{1} [0-2]{1}[0-9]{1}:[0-5]{1}[0-9]{1}:[0-6]{1}[0-9]{1}$",
+                 trimws(date))
+  return(check)
+}
+
+#' @describeIn date_formats Check format is YYYY-MM-DD HH:MM:SS.mmm
+#' @keywords internal
+is_ymd_hmsms <- function(date = NULL){
+  check <- grepl("^[1-9]{1}[0-9]{3}-[0-1]{1}[0-9]{1}-[0-3]{1}[0-9]{1} [0-2]{1}[0-9]{1}:[0-5]{1}[0-9]{1}:[0-6]{1}[0-9]{1}\\.[0-9]{3}$",
+                 trimws(date))
+  return(check)
+}
+
+
+#' Coerce to ISO 8601
+#'
+#' Coerce dates or datetimes to ISO 8601 format for Bamboo HR REST API.
+#'
+#' Input can be simply given as a character string. See \link{date_formats} for
+#' allowed format types.
 #'
-#' @author Mark Druffel, \email{mdruffel@propellerpdx.com}
+#' @name ISO_8601
+#'
+#' @return Character string in ISO 8601 format.
+NULL
 
 
-as_ISO8601_character <- function(time){
-  if (! is.null(time)) {
-    tm <- strftime(time, "%Y-%m-%dT%H:%M:%S")
-    time_z <- strftime(time, "%z") # format +0200
+#' @param datetime Character string. The datetime to coerce.
+#'
+#' @describeIn ISO_8601 Coerce datetime into ISO8601 format. This will convert
+#' represent the datetime relative to UTC using \code{+} notation. Milliseconds are
+#' removed.
+#'
+#' @keywords internal
+as_ISO8601_character <- function(datetime){
+  if (! is.null(datetime)) {
+    tm <- strftime(datetime, "%Y-%m-%dT%H:%M:%S")
+    time_z <- strftime(datetime, "%z") # format +0200
     # Add : between hour and rest
     time_z_colon <- paste0(
       substring(time_z, 1, 3),
@@ -23,36 +65,22 @@ as_ISO8601_character <- function(time){
   }
 }
 
-
-
-#is_ymd <- function(date = NULL) {
-#  check <- grepl("^[1-9]{1}[0-9]{3}-[0-1]{1}[0-9]{1}-[0-3]{1}[0-9]{1}$",
-#                 trimws(date))
-#  return(check)
-#}
-
-#is_ymd_hms <- function(date = NULL){
-#  check <- grepl("^[1-9]{1}[0-9]{3}-[0-1]{1}[0-9]{1}-[0-3]{1}[0-9]{1} [0-2]{1}[0-9]{1}:[0-5]{1}[0-9]{1}:[0-6]{1}[0-9]{1}$",
-#                 trimws(date))
-#  return(check)
-#}
-
-#is_ymd_hmsms <- function(date = NULL){
-#  check <- grepl("^[1-9]{1}[0-9]{3}-[0-1]{1}[0-9]{1}-[0-3]{1}[0-9]{1} [0-2]{1}[0-9]{1}:[0-5]{1}[0-9]{1}:[0-6]{1}[0-9]{1}\\.[0-9]{1}[0-9]{1}[0-9]{1}$",
-#                 trimws(date))
-#  return(check)
-#}
-
-#coerce_ISO8601 <- function(date){
-#  if(is_ymd(date)){
-#    input_date <- lubridate::ymd_hms(paste0(date, " 00:00:00"))
-#  }
-#  if(is_ymd_hms(date)){
-#    input_date <- lubridate::ymd_hms(date)
-#  }
-#  if(is_ymd_hmsms(date)){
-#    input_date <- lubridate::ymd_hms(date)
-#  }
-#  iso_date <- paste0(lubridate::format_ISO8601(input_date),"Z")
-#  return(iso_date)
-#}
+#' @param date Character string. The date to coerce.
+#'
+#' @describeIn ISO_8601 Coerce a date to ISO8601 format. This will convert the date
+#' into UTC (applying \code{Z} notation) and remove any milliseconds.
+#'
+#' @keywords internal
+coerce_ISO8601 <- function(date){
+  if(is_ymd(date)){
+    date <- lubridate::ymd_hms(paste0(date, " 00:00:00"))
+  } else if(is_ymd_hms(date)){
+    date <- lubridate::ymd_hms(date)
+  } else if(is_ymd_hmsms(date)){
+    date <- lubridate::ymd_hms(date)
+  } else {
+    stop("Date/datetime not in format ymd, ymd_hms, or ymd_hmsms. See ?date_formats.")
+  }
+  iso_date <- paste0(lubridate::format_ISO8601(date),"Z")
+  return(iso_date)
+}