Lightweight Wrapper to the ntfy.sh Service
OTHER License
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-"
)
library(ntfy)
ntfy (pronounce: notify) is a simple HTTP-based pub-sub notification service. It allows you to send notifications to your phone or desktop via scripts from any computer, entirely without signup, cost or setup. It's also open source if you want to run your own. Visit ntfy.sh for more details.
{ntfy} is a lightweight R wrapper for this service. The magic sauce is just
POST
and GET
calls equivalent to
curl -d "Process Complete 😀" ntfy.sh/yourSecretTopic
but made to work nicely in an R workflow.
You can install the development version of ntfy like so:
# install.packages("remotes")
remotes::install_github("jonocarroll/ntfy")
Follow the instructions at ntfy.sh to install any of the mobile apps or use the web app. No sign-up or account is necessary.
Choose a topic (note: this isn't a password-protected service, so choose something obscure) and subscribe to it on your device.
Add the topic as an environment variable, e.g.
usethis::edit_r_environ()
[...]
NTFY_TOPIC='yourSecretTopic'
#NTFY_SERVER='https://ntfy.sh'
The server will automatically be set to https://ntfy.sh unless you specify another.
This can be confirmed with
ntfy_server()
With the package loaded, you can now send notifications which should appear on your device
library(ntfy)
ntfy_send("test from R!")
This can be used in many ways. One would be to notify the completion of a process.
The ntfy_done()
function sends a notification with the (default) body
Process completed at <Sys.time()>
slow_process <- function(x) {
Sys.sleep(8) # sleep for 8 seconds
x
}
mtcars |>
head() |>
slow_process() |>
ntfy_done()
which results in a notification on subscribed devices
Process completed at 2023-07-04 17:00
When using the base R pipe |>
the piped commands are composed together by the
parser, so
f() |>
g() |>
h()
becomes
h(g(f()))
We can use this fact to time the running of a process if the last function
(above, h()
) is system.time()
. The ntfy_done_with_timing()
function does exactly
this
mtcars |>
head() |>
slow_process() |>
ntfy_done_with_timing()
which sends the notification
Process completed in 8.003s
Note: the {magrittr} pipe %>%
works differently and does not compose the same way, so this will
result in a very short time report. Wrapping an entire pipeline with ntfy_done_with_timing()
will work,
though
library(magrittr)
ntfy_done_with_timing(
mtcars %>%
head() %>%
slow_process()
)
sends
Process completed in 8.004s
If you're using a topic on a server that requires authentication, you can pass auth = TRUE
, along with a username and password:
ntfy_send(
"test from R!",
auth = TRUE,
username = "example",
password = "super-secret-password"
)
Alternatively, you can set these as environment variables and they'll get used
by ntfy_send()
automatically:
usethis::edit_r_environ()
[...]
NTFY_AUTH='TRUE'
NTFY_USERNAME='example'
NTFY_PASSWORD='super-secret-password'
ntfy_send("test from R!")
The history of the notifications sent can be retrieved as well, with control over how far back to search
ntfy_history(since = "1h")
structure(list(id = c("0oDpk4oisfNO", "4Fcy9kIL0m6Z", "AGXn4q0CirFT"
), time = c(1667988383L, 1667988413L, 1667990983L), event = c("message",
"message", "message"), topic = c("yourSecretTopic", "yourSecretTopic", "yourSecretTopic"
), message = c("test from R!", "Process completed at 2022-11-09 17:31:03", "Process completed in 8.003s")),
row.names = c(NA, -3L
), class = "data.frame")
The full ntfy.sh API should be supported, including sending a title and tags
{width=300}
{width=300}
Images can be sent within notifications by specifying as image
either the
filename or a ggplot2
object (which will be saved to a temporary file)
library(ggplot2)
p <- ggplot(mtcars, (aes(mpg, wt))) +
geom_point() +
geom_smooth() +
labs(title = "ggplot images in {ntfy}")
ntfy_send("ggplot2 images in notifications!",
tags = c("tada", "chart"),
image = p)
Supported tags (emoji) can be sent with the tags
argument (one or more). These can be searched or shown with show_emoji()
which will look for a given name in the compatible values, or search for it in the compatible metadata.
The compatible data is stored as emoji
data("emoji")
head(emoji)
with the tags stored as tags
for easy auto-complete
ntfy_send(message = "sending with tags!",
tags = c(tags$cat, tags$dog)
)
The compatible emoji can be shown with
show_emoji("rofl")
If the name is not found in aliases
(the compatible names) it will
be searched in tags
show_emoji("lol")
show_emoji("pet")
You can force this behaviour with
show_emoji("dog", search = TRUE)
Q: "Will you know what topics exist, can you spy on me?"
A: Refer to the FAQ
If this service is useful to you, consider donating to the developer via GitHub sponsors. If this package is useful to you, I also accept donations via GitHub sponsors.