diff --git a/DESCRIPTION b/DESCRIPTION index 235325a..bc780d6 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -19,6 +19,7 @@ Depends: Imports: ggplot2 (>= 4.0.0), jpeg, + jsonlite, png, stringr, gridExtra, diff --git a/NAMESPACE b/NAMESPACE index e4ef366..697ed47 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,5 +1,6 @@ # Generated by roxygen2: do not edit by hand +export(beep) export(add_logo) export(add_logo_ga) export(agresti_coull_interval) @@ -71,3 +72,4 @@ importFrom(stats,qnorm) importFrom(stats,runif) importFrom(stringdist,stringsim) importFrom(stringr,str_count) +importFrom(utils,flush.console) diff --git a/R/notifications.R b/R/notifications.R new file mode 100644 index 0000000..e7b56a9 --- /dev/null +++ b/R/notifications.R @@ -0,0 +1,153 @@ +#' Send a CLI beep / desktop notification +#' +#' Plays an audible beep in the terminal and/or sends a desktop notification +#' when a long-running R script completes or reaches a milestone. +#' +#' @param msg Character. Optional message to include in the notification. +#' When `type = "notify"`, this becomes the notification body. +#' @param type Character. Notification method: +#' - `"beep"` (default): emit a terminal bell character (`\007`). +#' Works in any terminal that supports the bell. +#' - `"notify"`: send a desktop notification via `notify-send` (Linux) or +#' `osascript` (macOS). Falls back to `"beep"` if neither tool is found. +#' - `"webhook"`: POST a JSON payload to a URL. Requires `url` argument. +#' - `"all"`: play beep + send desktop notification (webhook only if `url` +#' is provided). +#' @param url Character. Webhook URL for `type = "webhook"` or `"all"`. +#' A JSON payload is POSTed with keys `message`, `status`, and `timestamp`. +#' @param status Character. Status label for the notification (default `"done"`). +#' Used in the notification title and webhook payload. +#' @param timeout Numeric. Seconds to wait for the webhook POST to complete +#' (default `5`). Ignored for non-webhook types. +#' @param quiet Logical. If `TRUE`, suppress the terminal beep even when +#' `type` includes `"beep"`. Useful for silent background runs. +#' +#' @return Invisible `NULL`. +#' +#' @section Requirements: +#' - `type = "notify"` requires `notify-send` (Linux) or `osascript` (macOS). +#' - `type = "webhook"` requires network access to the provided URL. +#' +#' @section Examples: +#' \preformatted{ +#' # Simple terminal beep +#' beep() +#' +#' # Desktop notification with message +#' beep("Analysis complete!", type = "notify") +#' +#' # Send to a webhook (e.g., Slack, Discord, custom endpoint) +#' beep("Job finished", type = "webhook", +#' url = "https://hooks.slack.com/services/...") +#' +#' # Beep + desktop notification +#' beep("Processing done", type = "all") +#' } +#' +#' @export +#' +beep <- function(msg = "done", + type = c("beep", "notify", "webhook", "all"), + url = NULL, + status = "done", + timeout = 5, + quiet = FALSE) { + type <- match.arg(type) + + # -- Terminal beep ---------------------------------------------------------- + if (!quiet && grepl("beep", type)) { + cat("\007") + flush.console() + } + + # -- Desktop notification --------------------------------------------------- + if (grepl("notify", type)) { + .send_desktop_notify(msg, status) + } + + # -- Webhook ---------------------------------------------------------------- + if (grepl("webhook", type) && !is.null(url)) { + .send_webhook(url, msg, status, timeout) + } + + invisible(NULL) +} + + +# -- Internal helpers --------------------------------------------------------- + +#' Send a desktop notification via notify-send or osascript +#' +#' @param msg Message body +#' @param status Status label for the title +#' @keywords internal +.send_desktop_notify <- function(msg, status) { + # Linux: notify-send + if (.has_command("notify-send")) { + system2("notify-send", args = c(status, msg), + stdout = TRUE, stderr = TRUE) + return(invisible(NULL)) + } + + # macOS: osascript + if (.has_command("osascript")) { + system2("osascript", + args = c("-e", + paste0("display notification \"", msg, + "\" with title \"", status, "\"")), + stdout = TRUE, stderr = TRUE) + return(invisible(NULL)) + } + + # Neither tool available — silently skip + invisible(NULL) +} + + +#' POST a JSON payload to a webhook URL +#' +#' @param url Webhook URL +#' @param msg Message body +#' @param status Status label +#' @param timeout Seconds to wait for the request +#' @keywords internal +.send_webhook <- function(url, msg, status, timeout) { + payload <- jsonlite::toJSON(list( + message = msg, + status = status, + timestamp = format(Sys.time(), "%Y-%m-%dT%H:%M:%S%z") + ), auto_unbox = TRUE) + + # Use curl via system2() for maximum compatibility (no extra R deps). + # system2() passes arguments directly to the executable without shell + # interpolation, avoiding command injection. + if (.has_command("curl")) { + system2("curl", + args = c("-s", "-X", "POST", + "-H", "Content-Type: application/json", + "-d", payload, + url, + "--max-time", as.character(timeout)), + stdout = TRUE, stderr = TRUE) + } else if (.has_command("wget")) { + system2("wget", + args = c("-q", "-O", "/dev/null", + paste0("--post-data=", payload), + paste0("--header=Content-Type: application/json"), + paste0("--timeout=", timeout), + url), + stdout = TRUE, stderr = TRUE) + } + + invisible(NULL) +} + + +#' Check if a command exists on the system PATH +#' +#' @param cmd Command name +#' @return Logical +#' @keywords internal +.has_command <- function(cmd) { + Sys.which(cmd) != "" +} diff --git a/R/utils.R b/R/utils.R index 6a4fe8b..b1a0ca3 100644 --- a/R/utils.R +++ b/R/utils.R @@ -149,6 +149,9 @@ race_short_names <- function(x) { #' Sum a numeric that contains missing values and ignore missing values #' #' @param x a numeric vector +#' @param quiet Logical. If `TRUE` (default `FALSE`), suppress the warning +#' message. Useful when calling `na_sum()` inside a loop or `dplyr` pipeline +#' where the message would be emitted repeatedly. #' #' @return the sum, ignoring any missing values #' @export @@ -156,9 +159,12 @@ race_short_names <- function(x) { #' @examples #' x <- c(2, NA, 4, 9) #' na_sum(x) # 15 -na_sum <- function(x) { +#' na_sum(x, quiet = TRUE) # 15 (no message) +na_sum <- function(x, quiet = FALSE) { stopifnot(is.numeric(x)) - message("Taking a sum with missing values equal to 0, be careful!") + if (!quiet) { + message("Taking a sum with missing values equal to 0, be careful!") + } x <- na_zero(x) return(sum(x)) } diff --git a/inst/quarto/_brand.yml b/inst/quarto/_brand.yml index 73ad02a..d8c6ba3 100644 --- a/inst/quarto/_brand.yml +++ b/inst/quarto/_brand.yml @@ -2,65 +2,64 @@ # Optional but recommended — Quarto auto-applies these to HTML, PDF, and Revealjs. # https://quarto.org/docs/authoring/brand.html -brand: - meta: - name: Civilytics Consulting - description: Turning public data into clear, actionable analysis for public good. +meta: + name: Civilytics Consulting + description: Turning public data into clear, actionable analysis for public good. - logo: - small: assets/logo/civilytics-mark.svg - medium: assets/logo/civilytics-wordmark.svg - large: assets/logo/civilytics-wordmark.svg +logo: + small: assets/logo/civilytics-mark.svg + medium: assets/logo/civilytics-wordmark.svg + large: assets/logo/civilytics-wordmark.svg - color: - palette: - paper: "#FAF7F2" - paper-2: "#F2EDE4" - ink: "#0E1A2B" - ink-2: "#2B3A52" - ink-3: "#5A6A82" - navy: "#22406A" - ember: "#C25311" - ember-2: "#923D00" - teal: "#1F6F70" - plum: "#6B3A5E" - moss: "#4A6B2F" - brass: "#B8751C" - background: paper - foreground: ink - primary: navy - secondary: ember - success: moss - info: navy - warning: "#9A5F18" - danger: "#A6271D" - light: paper-2 - dark: ink - link: navy +color: + palette: + paper: "#FAF7F2" + paper-2: "#F2EDE4" + ink: "#0E1A2B" + ink-2: "#2B3A52" + ink-3: "#5A6A82" + navy: "#22406A" + ember: "#C25311" + ember-2: "#923D00" + teal: "#1F6F70" + plum: "#6B3A5E" + moss: "#4A6B2F" + brass: "#B8751C" + background: paper + foreground: ink + primary: navy + secondary: ember + success: moss + info: navy + warning: "#9A5F18" + danger: "#A6271D" + light: paper-2 + dark: ink + link: navy - typography: - fonts: - - family: "Source Serif 4" - source: google - - family: "Inter" - source: google - - family: "JetBrains Mono" - source: google - - family: "Libre Franklin" - source: google - base: - family: Inter - size: 1rem - line-height: 1.65 - headings: - family: "Libre Franklin" - weight: 800 - style: normal - line-height: 1.08 - color: ink - monospace: - family: "JetBrains Mono" - size: 0.92em - link: - color: navy - decoration: underline +typography: + fonts: + - family: "Source Serif 4" + source: google + - family: "Inter" + source: google + - family: "JetBrains Mono" + source: google + - family: "Libre Franklin" + source: google + base: + family: Inter + size: 1rem + line-height: 1.65 + headings: + family: "Libre Franklin" + weight: 800 + style: normal + line-height: 1.08 + color: ink + monospace: + family: "JetBrains Mono" + size: 0.92em + link: + color: navy + decoration: underline diff --git a/man/beep.Rd b/man/beep.Rd new file mode 100644 index 0000000..706e2ca --- /dev/null +++ b/man/beep.Rd @@ -0,0 +1,71 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/notifications.R +\name{beep} +\alias{beep} +\title{Send a CLI beep / desktop notification} +\usage{ +beep( + msg = "done", + type = c("beep", "notify", "webhook", "all"), + url = NULL, + status = "done", + timeout = 5, + quiet = FALSE +) +} +\arguments{ +\item{msg}{Character. Optional message to include in the notification. +When \code{type = "notify"}, this becomes the notification body.} + +\item{type}{Character. Notification method: +\itemize{ +\item \code{"beep"} (default): emit a terminal bell character. +Works in any terminal that supports the bell. +\item \code{"notify"}: send a desktop notification via \code{notify-send} (Linux) or +\code{osascript} (macOS). Falls back to \code{"beep"} if neither tool is found. +\item \code{"webhook"}: POST a JSON payload to a URL. Requires \code{url} argument. +\item \code{"all"}: play beep + send desktop notification (webhook only if \code{url} +is provided). +}} + +\item{url}{Character. Webhook URL for \code{type = "webhook"} or \code{"all"}. +A JSON payload is POSTed with keys \code{message}, \code{status}, and \code{timestamp}.} + +\item{status}{Character. Status label for the notification (default \code{"done"}). +Used in the notification title and webhook payload.} + +\item{timeout}{Numeric. Seconds to wait for the webhook POST to complete +(default \code{5}). Ignored for non-webhook types.} + +\item{quiet}{Logical. If \code{TRUE}, suppress the terminal beep even when +\code{type} includes \code{"beep"}. Useful for silent background runs.} +} +\value{ +Invisible \code{NULL}. +} +\description{ +Plays an audible beep in the terminal and/or sends a desktop notification +when a long-running R script completes or reaches a milestone. +} +\section{Requirements}{ +\itemize{ +\item \code{type = "notify"} requires \code{notify-send} (Linux) or \code{osascript} (macOS). +\item \code{type = "webhook"} requires network access to the provided URL. +} +} +\section{Examples}{ +\preformatted{ +# Simple terminal beep +beep() + +# Desktop notification with message +beep("Analysis complete!", type = "notify") + +# Send to a webhook (e.g., Slack, Discord, custom endpoint) +beep("Job finished", type = "webhook", + url = "https://hooks.slack.com/services/...") + +# Beep + desktop notification +beep("Processing done", type = "all") +} +} diff --git a/man/na_sum.Rd b/man/na_sum.Rd index 28a7176..dbcc52f 100644 --- a/man/na_sum.Rd +++ b/man/na_sum.Rd @@ -4,10 +4,14 @@ \alias{na_sum} \title{Sum a numeric that contains missing values and ignore missing values} \usage{ -na_sum(x) +na_sum(x, quiet = FALSE) } \arguments{ \item{x}{a numeric vector} + +\item{quiet}{Logical. If \code{TRUE} (default \code{FALSE}), suppress the warning +message. Useful when calling \code{na_sum()} inside a loop or \code{dplyr} pipeline +where the message would be emitted repeatedly.} } \value{ the sum, ignoring any missing values @@ -18,4 +22,5 @@ Sum a numeric that contains missing values and ignore missing values \examples{ x <- c(2, NA, 4, 9) na_sum(x) # 15 +na_sum(x, quiet = TRUE) # 15 (no message) } diff --git a/tests/testthat/test_notifications.R b/tests/testthat/test_notifications.R new file mode 100644 index 0000000..e6e0b67 --- /dev/null +++ b/tests/testthat/test_notifications.R @@ -0,0 +1,56 @@ +# Test beep / notification function + +context("Test beep() function") + +test_that("beep() returns invisibly", { + expect_invisible(beep()) + expect_invisible(beep("test", type = "beep")) + expect_invisible(beep("test", type = "all")) +}) + +test_that("beep() with quiet=TRUE produces no output", { + expect_silent(beep("test", type = "beep", quiet = TRUE)) +}) + +test_that("beep() with type=notify is silent when no tools available", { + # When notify-send and osascript are both absent, should be silent + expect_silent(beep("test", type = "notify")) +}) + +test_that("beep() with type=webhook and no URL is silent", { + expect_silent(beep("test", type = "webhook")) +}) + +test_that("beep(type='all') exercises both beep and notify paths", { + # type="all" should trigger the terminal beep (unless quiet) and + # attempt a desktop notification. We verify by checking that the + # function returns invisibly and does not error when notify-send + # is absent (which is the case in CI). + expect_invisible(beep("all-test", type = "all")) + expect_invisible(beep("all-test", type = "all", quiet = TRUE)) +}) + +test_that("notification helpers use system2() to prevent command injection", { + # Security regression: .send_webhook and .send_desktop_notify must + # use system2() with separate args, never system() with shell + # interpolation. system2() passes arguments directly to the + # executable without going through a shell, so shell metacharacters + # in msg, status, url, or payload are treated as literal data. + + webhook_body <- deparse(body(.send_webhook)) + notify_body <- deparse(body(.send_desktop_notify)) + + # Must use system2 + expect_true(any(grepl("system2", webhook_body)), + info = ".send_webhook() must use system2() to avoid shell injection") + expect_true(any(grepl("system2", notify_body)), + info = ".send_desktop_notify() must use system2() to avoid shell injection") + + # Must NOT use system( with string interpolation (system("curl ...")) + # We look for system( followed by a string literal (the old pattern). + # system2 calls look like system2("curl", args = ...) which is fine. + expect_false(any(grepl('system\\(\\s*"', webhook_body)), + info = ".send_webhook() must not use system() with interpolated strings") + expect_false(any(grepl('system\\(\\s*"', notify_body)), + info = ".send_desktop_notify() must not use system() with interpolated strings") +}) diff --git a/tests/testthat/test_utils.R b/tests/testthat/test_utils.R index acba675..9dd4d11 100644 --- a/tests/testthat/test_utils.R +++ b/tests/testthat/test_utils.R @@ -58,6 +58,12 @@ test_that("na_sum fails with non-numerics", { expect_error(na_sum(as.factor(1:10))) }) +test_that("na_sum quiet=TRUE suppresses the message", { + expect_message(na_sum(c(1:10, NA)), "Taking a sum") + expect_silent(na_sum(c(1:10, NA), quiet = TRUE)) + expect_equal(na_sum(c(1:10, NA), quiet = TRUE), 55) +}) + context("Test Utilities - Pretty Count")