use crate::deep_links::DeepLink;
pub use crate::permissions::PermissionStatus;
use crate::runtime::current_runtime;
use crate::task::WorkerTask;
use crate::{Error, Operation, Result};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::fmt;
use std::time::{Duration, SystemTime, UNIX_EPOCH};
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct NotificationId(String);
impl NotificationId {
pub fn parse(value: impl Into<String>) -> Result<Self> {
let value = value.into();
validate_id(&value)?;
Ok(Self(value))
}
pub fn as_str(&self) -> &str {
&self.0
}
}
impl fmt::Display for NotificationId {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
self.0.fmt(formatter)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(transparent)]
pub struct UnixTimestamp(pub i64);
impl UnixTimestamp {
pub fn from_system_time(time: SystemTime) -> Result<Self> {
match time.duration_since(UNIX_EPOCH) {
Ok(duration) => {
let millis = i64::try_from(duration.as_millis())
.map_err(|_| Error::invalid("scheduled time", "timestamp is too large"))?;
Ok(Self(millis))
}
Err(error) => {
let millis = i64::try_from(error.duration().as_millis()).map_err(|_| {
Error::invalid("scheduled time", "timestamp is too far before the epoch")
})?;
Ok(Self(-millis))
}
}
}
pub fn now() -> Result<Self> {
Self::from_system_time(SystemTime::now())
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NotificationAction {
pub id: String,
pub title: String,
pub foreground: bool,
pub authentication_required: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case", tag = "mode", content = "name")]
pub enum SoundMode {
Default,
Silent,
Named(String),
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Notification {
pub id: NotificationId,
pub title: String,
pub body: String,
pub subtitle: Option<String>,
pub payload: Option<Value>,
pub deep_link: Option<DeepLink>,
pub scheduled_at: Option<UnixTimestamp>,
pub repeat_interval: Option<Duration>,
pub android_channel: Option<String>,
pub actions: Vec<NotificationAction>,
pub badge: Option<u32>,
pub sound: SoundMode,
}
impl Notification {
pub fn new(id: impl Into<String>, title: impl Into<String>, body: impl Into<String>) -> Self {
Self {
id: NotificationId(id.into()),
title: title.into(),
body: body.into(),
subtitle: None,
payload: None,
deep_link: None,
scheduled_at: None,
repeat_interval: None,
android_channel: None,
actions: Vec::new(),
badge: None,
sound: SoundMode::Default,
}
}
pub fn subtitle(mut self, subtitle: impl Into<String>) -> Self {
self.subtitle = Some(subtitle.into());
self
}
pub fn payload(mut self, payload: impl Serialize) -> Result<Self> {
self.payload = Some(
serde_json::to_value(payload)
.map_err(|error| Error::invalid("notification payload", error.to_string()))?,
);
Ok(self)
}
pub fn deep_link(mut self, deep_link: DeepLink) -> Self {
self.deep_link = Some(deep_link);
self
}
pub fn scheduled_at(mut self, scheduled_at: UnixTimestamp) -> Self {
self.scheduled_at = Some(scheduled_at);
self
}
pub fn repeat_every(mut self, interval: Duration) -> Self {
self.repeat_interval = Some(interval);
self
}
pub fn android_channel(mut self, channel: impl Into<String>) -> Self {
self.android_channel = Some(channel.into());
self
}
pub fn action(mut self, action: NotificationAction) -> Self {
self.actions.push(action);
self
}
pub const fn badge(mut self, badge: u32) -> Self {
self.badge = Some(badge);
self
}
pub fn sound(mut self, sound: SoundMode) -> Self {
self.sound = sound;
self
}
fn validate(&self, scheduling: bool) -> Result<()> {
validate_id(self.id.as_str())?;
if self.title.trim().is_empty() && self.body.trim().is_empty() {
return Err(Error::invalid(
"notification content",
"title and body cannot both be empty",
));
}
if scheduling && self.scheduled_at.is_none() {
return Err(Error::invalid(
"scheduled notification",
"scheduled_at must be set before schedule",
));
}
if self
.repeat_interval
.is_some_and(|interval| interval.is_zero())
{
return Err(Error::invalid(
"repeat interval",
"must be greater than zero",
));
}
for action in &self.actions {
if action.id.trim().is_empty() || action.title.trim().is_empty() {
return Err(Error::invalid(
"notification action",
"id and title must be non-empty",
));
}
}
Ok(())
}
}
fn validate_id(value: &str) -> Result<()> {
if value.trim().is_empty() {
return Err(Error::invalid("notification id", "must not be empty"));
}
if value.len() > 128 {
return Err(Error::invalid(
"notification id",
"must not exceed 128 bytes",
));
}
Ok(())
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PendingNotification {
pub notification: Notification,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DeliveredNotification {
pub notification: Notification,
pub delivered_at: UnixTimestamp,
}
pub fn is_supported() -> bool {
current_runtime().supports(Operation::NotificationSchedule)
}
pub fn can_request_permission() -> bool {
current_runtime().supports(Operation::NotificationPermissionRequest)
}
pub fn can_show_now() -> bool {
current_runtime().supports(Operation::NotificationShowNow)
}
pub fn permission_status() -> Result<PermissionStatus> {
let runtime = current_runtime();
runtime.ensure_supported(Operation::NotificationPermissionStatus)?;
runtime.backend().notification_permission_status()
}
pub async fn request_permission() -> Result<PermissionStatus> {
let runtime = current_runtime();
runtime.ensure_supported(Operation::NotificationPermissionRequest)?;
let backend = runtime.backend_arc();
WorkerTask::spawn(move || backend.notification_request_permission())
.await
.map_err(|_| {
Error::backend(
Operation::NotificationPermissionRequest,
"notification permission worker panicked",
)
})?
}
pub fn schedule(notification: Notification) -> Result<()> {
notification.validate(true)?;
let runtime = current_runtime();
runtime.ensure_supported(Operation::NotificationSchedule)?;
runtime.backend().notification_schedule(notification)
}
pub fn show_now(mut notification: Notification) -> Result<()> {
notification.scheduled_at = None;
notification.repeat_interval = None;
notification.validate(false)?;
let runtime = current_runtime();
runtime.ensure_supported(Operation::NotificationShowNow)?;
runtime.backend().notification_show_now(notification)
}
pub fn cancel(id: &NotificationId) -> Result<()> {
let runtime = current_runtime();
runtime.ensure_supported(Operation::NotificationCancel)?;
runtime.backend().notification_cancel(id)
}
pub fn cancel_all() -> Result<()> {
let runtime = current_runtime();
runtime.ensure_supported(Operation::NotificationCancel)?;
runtime.backend().notification_cancel_all()
}
pub fn pending() -> Result<Vec<PendingNotification>> {
let runtime = current_runtime();
runtime.ensure_supported(Operation::NotificationPending)?;
runtime.backend().notification_pending()
}
pub fn delivered() -> Result<Vec<DeliveredNotification>> {
let runtime = current_runtime();
runtime.ensure_supported(Operation::NotificationDelivered)?;
runtime.backend().notification_delivered()
}
#[cfg(test)]
mod tests {
use super::*;
use crate::task::block_on;
use crate::testing::TestRuntime;
use parking_lot::Mutex;
use std::sync::Arc;
#[test]
fn test_backend_covers_full_notification_lifecycle() {
let runtime = TestRuntime::new();
let _guard = runtime.enter();
assert_eq!(
permission_status().unwrap(),
PermissionStatus::NotDetermined
);
assert_eq!(
block_on(request_permission()).unwrap(),
PermissionStatus::Granted
);
let request =
Notification::new("later", "Hello", "from a test").scheduled_at(UnixTimestamp(2_000));
schedule(request).unwrap();
assert_eq!(pending().unwrap().len(), 1);
cancel(&NotificationId::parse("later").unwrap()).unwrap();
assert!(pending().unwrap().is_empty());
show_now(Notification::new("now", "Hello", "now")).unwrap();
assert_eq!(delivered().unwrap().len(), 1);
}
#[test]
fn models_round_trip_through_json() {
let notification = Notification::new("id", "Title", "Body")
.scheduled_at(UnixTimestamp(42))
.repeat_every(Duration::from_secs(61));
let json = serde_json::to_string(¬ification).unwrap();
assert_eq!(
serde_json::from_str::<Notification>(&json).unwrap(),
notification
);
}
#[test]
fn unsupported_schedule_points_to_notifications_capability() {
let runtime = TestRuntime::new();
let _guard = runtime.enter();
runtime.set_supported(Operation::NotificationSchedule, false);
let notification =
Notification::new("later", "Hello", "from a test").scheduled_at(UnixTimestamp(42));
let error = schedule(notification).unwrap_err();
assert_eq!(error, Error::unsupported(Operation::NotificationSchedule));
assert!(
error
.to_string()
.contains("`cargo ferry add notifications`")
);
}
#[test]
fn notification_open_reaches_typed_event_handler() {
let runtime = TestRuntime::new();
let _guard = runtime.enter();
let opened = Arc::new(Mutex::new(None));
let observed = Arc::clone(&opened);
let _subscription =
crate::app_events::on_notification_opened(move |id, action, payload, deep_link| {
*observed.lock() = Some((id, action, payload, deep_link));
});
runtime.open_notification(
NotificationId::parse("message").unwrap(),
Some("reply".to_owned()),
Some(serde_json::json!({"thread": 7})),
None,
);
let opened = opened.lock().clone().unwrap();
assert_eq!(opened.0.as_str(), "message");
assert_eq!(opened.1.as_deref(), Some("reply"));
assert_eq!(opened.2.unwrap()["thread"], 7);
}
}