@choochmeque/tauri-plugin-notifications-api 0.3.1 → 0.4.0

package/README.md

@@ -45,7 +45,7 @@ Add the plugin to your Tauri project's `Cargo.toml`:
 
 ```toml
 [dependencies]
-tauri-plugin-notifications = "0.3"
+tauri-plugin-notifications = "0.4"
 ```
 
 ### Push Notifications Feature
@@ -68,6 +68,33 @@ Without this feature enabled:
 - Push notification registration code is disabled
 - The `registerForPushNotifications()` function will return an error if called
 
+### Desktop Notification Backend (notify-rust)
+
+The `notify-rust` feature is **enabled by default** and provides cross-platform desktop notifications using the [notify-rust](https://crates.io/crates/notify-rust) crate.
+
+**When to use notify-rust (default):**
+- Simple notifications on Linux, macOS, and Windows
+- Cross-platform consistency
+- Basic notification features (title, body, icon)
+
+**When to disable notify-rust:**
+- You need native Windows toast notifications with advanced features (actions, hero images, scheduling)
+- You want platform-specific notification features on macOS/Windows
+
+To disable `notify-rust` and use native platform implementations:
+
+```toml
+[dependencies]
+tauri-plugin-notifications = { version = "0.3", default-features = false }
+```
+
+To disable `notify-rust` and enable push notifications:
+
+```toml
+[dependencies]
+tauri-plugin-notifications = { version = "0.3", default-features = false, features = ["push-notifications"] }
+```
+
 Configure the plugin permissions in your `capabilities/default.json`:
 
 ```json
@@ -89,6 +116,24 @@ fn main() {
 }
 ```
 
+## Example App
+
+An example app is available in [`examples/notifications-demo`](examples/notifications-demo) demonstrating all plugin features:
+
+- Permission management and push notifications (mobile)
+- Basic, scheduled, and styled notifications
+- Interactive notifications with action buttons
+- Notification channels (Android)
+- Pending and active notification management
+- Event listeners with logging
+
+**Run it:**
+```bash
+cd examples/notifications-demo
+pnpm install
+pnpm tauri dev
+```
+
 ## Usage
 
 ### JavaScript/TypeScript

package/dist-js/index.cjs

@@ -145,6 +145,24 @@ async function requestPermission() {
 async function registerForPushNotifications() {
     return await core.invoke("plugin:notifications|register_for_push_notifications");
 }
+/**
+ * Unregisters the app from push notifications (mobile).
+ *
+ * This removes the device's push notification token and stops receiving
+ * remote push notifications.
+ *
+ * @example
+ * ```typescript
+ * import { unregisterForPushNotifications } from '@choochmeque/tauri-plugin-notifications-api';
+ * await unregisterForPushNotifications();
+ * console.log('Unregistered from push notifications');
+ * ```
+ *
+ * @returns A promise resolving when unregistration is complete.
+ */
+async function unregisterForPushNotifications() {
+    return await core.invoke("plugin:notifications|unregister_for_push_notifications");
+}
 /**
  * Sends a notification to the user.
  * @example
@@ -230,7 +248,7 @@ async function cancel(notifications) {
  * @returns A promise indicating the success or failure of the operation.
  */
 async function cancelAll() {
-    await core.invoke("plugin:notifications|cancel");
+    await core.invoke("plugin:notifications|cancel_all");
 }
 /**
  * Retrieves the list of active notifications.
@@ -293,7 +311,7 @@ async function removeAllActive() {
  * @returns A promise indicating the success or failure of the operation.
  */
 async function createChannel(channel) {
-    await core.invoke("plugin:notifications|create_channel", { ...channel });
+    await core.invoke("plugin:notifications|create_channel", { channel });
 }
 /**
  * Removes the channel with the given identifier.
@@ -321,7 +339,7 @@ async function removeChannel(id) {
  * @returns A promise resolving to the list of notification channels.
  */
 async function channels() {
-    return await core.invoke("plugin:notifications|listChannels");
+    return await core.invoke("plugin:notifications|list_channels");
 }
 /**
  * Registers a listener for incoming notifications.
@@ -361,6 +379,42 @@ async function onNotificationReceived(cb) {
 async function onAction(cb) {
     return await core.addPluginListener("notifications", "actionPerformed", cb);
 }
+/**
+ * Registers a listener for notification click/tap events.
+ * This fires when the user taps on a notification (both push and local).
+ *
+ * This function handles cold-start scenarios where the app is launched by
+ * tapping a notification. Any pending notification click data is automatically
+ * delivered when the listener is registered.
+ *
+ * @example
+ * ```typescript
+ * import { onNotificationClicked } from '@choochmeque/tauri-plugin-notifications-api';
+ * const unlisten = await onNotificationClicked((data) => {
+ *   console.log('Notification clicked, id:', data.id);
+ *   console.log('Custom data:', data.data);
+ * });
+ * ```
+ *
+ * @param cb - Callback function to handle notification clicks.
+ * @returns A promise resolving to a function that removes the listener.
+ */
+async function onNotificationClicked(cb) {
+    const listener = await core.addPluginListener("notifications", "notificationClicked", cb);
+    // Tell native side listener is active (triggers pending if any)
+    await core.invoke("plugin:notifications|set_click_listener_active", {
+        active: true,
+    });
+    // Return wrapped listener that notifies native side on unregister
+    return {
+        unregister: async () => {
+            await core.invoke("plugin:notifications|set_click_listener_active", {
+                active: false,
+            });
+            return listener.unregister();
+        },
+    };
+}
 
 exports.Schedule = Schedule;
 exports.active = active;
@@ -370,6 +424,7 @@ exports.channels = channels;
 exports.createChannel = createChannel;
 exports.isPermissionGranted = isPermissionGranted;
 exports.onAction = onAction;
+exports.onNotificationClicked = onNotificationClicked;
 exports.onNotificationReceived = onNotificationReceived;
 exports.pending = pending;
 exports.registerActionTypes = registerActionTypes;
@@ -379,3 +434,4 @@ exports.removeAllActive = removeAllActive;
 exports.removeChannel = removeChannel;
 exports.requestPermission = requestPermission;
 exports.sendNotification = sendNotification;
+exports.unregisterForPushNotifications = unregisterForPushNotifications;

package/dist-js/index.d.ts

@@ -387,6 +387,22 @@ declare function requestPermission(): Promise<NotificationPermission>;
  * @returns A promise resolving to the device push token.
  */
 declare function registerForPushNotifications(): Promise<string>;
+/**
+ * Unregisters the app from push notifications (mobile).
+ *
+ * This removes the device's push notification token and stops receiving
+ * remote push notifications.
+ *
+ * @example
+ * ```typescript
+ * import { unregisterForPushNotifications } from '@choochmeque/tauri-plugin-notifications-api';
+ * await unregisterForPushNotifications();
+ * console.log('Unregistered from push notifications');
+ * ```
+ *
+ * @returns A promise resolving when unregistration is complete.
+ */
+declare function unregisterForPushNotifications(): Promise<string>;
 /**
  * Sends a notification to the user.
  * @example
@@ -574,5 +590,35 @@ declare function onNotificationReceived(cb: (notification: Options) => void): Pr
  * @returns A promise resolving to a function that removes the listener.
  */
 declare function onAction(cb: (notification: Options) => void): Promise<PluginListener>;
-export type { Attachment, Options, Action, ActionType, PendingNotification, ActiveNotification, Channel, ScheduleInterval, };
-export { Importance, Visibility, sendNotification, requestPermission, isPermissionGranted, registerForPushNotifications, registerActionTypes, pending, cancel, cancelAll, active, removeActive, removeAllActive, createChannel, removeChannel, channels, onNotificationReceived, onAction, Schedule, ScheduleEvery, };
+/**
+ * Data received when a notification is clicked/tapped.
+ */
+interface NotificationClickedData {
+    /** Notification ID */
+    id: number;
+    /** Custom data payload attached to the notification */
+    data?: Record<string, string>;
+}
+/**
+ * Registers a listener for notification click/tap events.
+ * This fires when the user taps on a notification (both push and local).
+ *
+ * This function handles cold-start scenarios where the app is launched by
+ * tapping a notification. Any pending notification click data is automatically
+ * delivered when the listener is registered.
+ *
+ * @example
+ * ```typescript
+ * import { onNotificationClicked } from '@choochmeque/tauri-plugin-notifications-api';
+ * const unlisten = await onNotificationClicked((data) => {
+ *   console.log('Notification clicked, id:', data.id);
+ *   console.log('Custom data:', data.data);
+ * });
+ * ```
+ *
+ * @param cb - Callback function to handle notification clicks.
+ * @returns A promise resolving to a function that removes the listener.
+ */
+declare function onNotificationClicked(cb: (data: NotificationClickedData) => void): Promise<PluginListener>;
+export type { Attachment, Options, Action, ActionType, PendingNotification, ActiveNotification, Channel, ScheduleInterval, NotificationClickedData, };
+export { Importance, Visibility, sendNotification, requestPermission, isPermissionGranted, registerForPushNotifications, unregisterForPushNotifications, registerActionTypes, pending, cancel, cancelAll, active, removeActive, removeAllActive, createChannel, removeChannel, channels, onNotificationReceived, onAction, onNotificationClicked, Schedule, ScheduleEvery, };

package/dist-js/index.js

@@ -143,6 +143,24 @@ async function requestPermission() {
 async function registerForPushNotifications() {
     return await invoke("plugin:notifications|register_for_push_notifications");
 }
+/**
+ * Unregisters the app from push notifications (mobile).
+ *
+ * This removes the device's push notification token and stops receiving
+ * remote push notifications.
+ *
+ * @example
+ * ```typescript
+ * import { unregisterForPushNotifications } from '@choochmeque/tauri-plugin-notifications-api';
+ * await unregisterForPushNotifications();
+ * console.log('Unregistered from push notifications');
+ * ```
+ *
+ * @returns A promise resolving when unregistration is complete.
+ */
+async function unregisterForPushNotifications() {
+    return await invoke("plugin:notifications|unregister_for_push_notifications");
+}
 /**
  * Sends a notification to the user.
  * @example
@@ -228,7 +246,7 @@ async function cancel(notifications) {
  * @returns A promise indicating the success or failure of the operation.
  */
 async function cancelAll() {
-    await invoke("plugin:notifications|cancel");
+    await invoke("plugin:notifications|cancel_all");
 }
 /**
  * Retrieves the list of active notifications.
@@ -291,7 +309,7 @@ async function removeAllActive() {
  * @returns A promise indicating the success or failure of the operation.
  */
 async function createChannel(channel) {
-    await invoke("plugin:notifications|create_channel", { ...channel });
+    await invoke("plugin:notifications|create_channel", { channel });
 }
 /**
  * Removes the channel with the given identifier.
@@ -319,7 +337,7 @@ async function removeChannel(id) {
  * @returns A promise resolving to the list of notification channels.
  */
 async function channels() {
-    return await invoke("plugin:notifications|listChannels");
+    return await invoke("plugin:notifications|list_channels");
 }
 /**
  * Registers a listener for incoming notifications.
@@ -359,5 +377,41 @@ async function onNotificationReceived(cb) {
 async function onAction(cb) {
     return await addPluginListener("notifications", "actionPerformed", cb);
 }
+/**
+ * Registers a listener for notification click/tap events.
+ * This fires when the user taps on a notification (both push and local).
+ *
+ * This function handles cold-start scenarios where the app is launched by
+ * tapping a notification. Any pending notification click data is automatically
+ * delivered when the listener is registered.
+ *
+ * @example
+ * ```typescript
+ * import { onNotificationClicked } from '@choochmeque/tauri-plugin-notifications-api';
+ * const unlisten = await onNotificationClicked((data) => {
+ *   console.log('Notification clicked, id:', data.id);
+ *   console.log('Custom data:', data.data);
+ * });
+ * ```
+ *
+ * @param cb - Callback function to handle notification clicks.
+ * @returns A promise resolving to a function that removes the listener.
+ */
+async function onNotificationClicked(cb) {
+    const listener = await addPluginListener("notifications", "notificationClicked", cb);
+    // Tell native side listener is active (triggers pending if any)
+    await invoke("plugin:notifications|set_click_listener_active", {
+        active: true,
+    });
+    // Return wrapped listener that notifies native side on unregister
+    return {
+        unregister: async () => {
+            await invoke("plugin:notifications|set_click_listener_active", {
+                active: false,
+            });
+            return listener.unregister();
+        },
+    };
+}
 
-export { Importance, Schedule, ScheduleEvery, Visibility, active, cancel, cancelAll, channels, createChannel, isPermissionGranted, onAction, onNotificationReceived, pending, registerActionTypes, registerForPushNotifications, removeActive, removeAllActive, removeChannel, requestPermission, sendNotification };
+export { Importance, Schedule, ScheduleEvery, Visibility, active, cancel, cancelAll, channels, createChannel, isPermissionGranted, onAction, onNotificationClicked, onNotificationReceived, pending, registerActionTypes, registerForPushNotifications, removeActive, removeAllActive, removeChannel, requestPermission, sendNotification, unregisterForPushNotifications };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choochmeque/tauri-plugin-notifications-api",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "license": "MIT",
   "author": "You",
   "description": "A Tauri v2 plugin for sending notifications on desktop and mobile platforms with support for system notifications and push delivery via FCM and APNs.",
@@ -41,7 +41,7 @@
     "rollup": "^4.52.4",
     "tslib": "^2.6.2",
     "typescript": "^5.3.3",
-    "prettier": "3.7.3",
+    "prettier": "3.7.4",
     "vitest": "^2.1.8"
   },
   "scripts": {