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
2026-06-03 19:08:48 +00:00
parent 2f1cdcde52
commit 75b9a73165
4 changed files with 79 additions and 1 deletions
@@ -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")
+}
+}