From 75b9a731655bacf372832c47abd29cfad12062ce Mon Sep 17 00:00:00 2001
From: Jared Knowles <jared@civilytics.com>
Date: Wed, 3 Jun 2026 19:08:48 +0000
Subject: [PATCH] Fix CI warnings: add jsonlite dep, flush.console import, Rd
 docs

- Add jsonlite to Imports (used by beep() webhook)
- Add importFrom(utils, flush.console) to NAMESPACE
- Update na_sum.Rd to include quiet parameter
- Create beep.Rd documentation
---
 DESCRIPTION   |  1 +
 NAMESPACE     |  1 +
 man/beep.Rd   | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++
 man/na_sum.Rd |  7 ++++-
 4 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100644 man/beep.Rd

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 7c6473a..697ed47 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -72,3 +72,4 @@ importFrom(stats,qnorm)
 importFrom(stats,runif)
 importFrom(stringdist,stringsim)
 importFrom(stringr,str_count)
+importFrom(utils,flush.console)
diff --git a/man/beep.Rd b/man/beep.Rd
new file mode 100644
index 0000000..a977408
--- /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 (\code{\char"007}).
+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)
 }