@choochmeque/tauri-plugin-notifications-api 0.4.5 → 0.5.0-rc.3

package/README.md

@@ -6,7 +6,7 @@
 
 # Tauri Plugin Notifications
 
-A Tauri v2 plugin for sending notifications on desktop and mobile platforms. Send toast notifications (brief auto-expiring OS window elements) with support for rich content, scheduling, actions, channels, and push delivery via FCM and APNs.
+A Tauri v2 plugin for sending notifications on desktop and mobile platforms. Send toast notifications (brief auto-expiring OS window elements) with support for rich content, scheduling, actions, channels, and push delivery via FCM, APNs, and UnifiedPush.
 
 ## Features
 
@@ -25,7 +25,7 @@ A Tauri v2 plugin for sending notifications on desktop and mobile platforms. Sen
 
 - **macOS**: Native notification center integration
 - **Windows**: Windows notification system
-- **Linux**: notify-rust with desktop notification support
+- **Linux**: notify-rust with desktop notification support; push notifications via UnifiedPush
 - **iOS**: User Notifications framework
 - **Android**: Android notification system with channels
 
@@ -59,9 +59,12 @@ tauri-plugin-notifications = { version = "0.4", features = ["push-notifications"
 
 This enables:
 - Firebase Cloud Messaging support on Android
-- APNs (Apple Push Notification service) support on iOS
+- APNs (Apple Push Notification service) support on iOS and macOS
+- UnifiedPush support on Linux (D-Bus distributor protocol)
 
-**Note:** Push notifications are currently supported on mobile platforms (iOS and Android) only. macOS and Windows support is not yet available.
+**Note:** Push notifications are currently supported on iOS, Android, macOS, and Linux. Windows support is not yet available.
+
+On Linux you also need a UnifiedPush *distributor* app installed (ntfy, NextPush, Conversations, etc. — see the [distributor list](https://unifiedpush.org/users/distributors/)). The plugin itself is stateless: any distributor selection or client token you set lives only for the current process. See [Linux UnifiedPush Setup](#linux-unifiedpush-setup) below for details.
 
 Without this feature enabled:
 - Firebase dependencies are not included in Android builds
@@ -448,9 +451,35 @@ Requests the permission to send notifications.
 **Returns:** `Promise<'granted' | 'denied' | 'default'>`
 
 ### `registerForPushNotifications()`
-Registers the app for push notifications (mobile only). On Android, this retrieves the FCM device token. On iOS, this requests permissions and registers for remote notifications.
+Registers the app for push notifications. On Android this retrieves the FCM device token; on iOS this requests permission and registers for remote notifications; on Linux this registers with the selected UnifiedPush distributor.
+
+**Returns:** `Promise<string>` — a platform-specific identifier:
+- iOS: APNs device token
+- Android: FCM device token
+- Linux: UnifiedPush endpoint URL (the URL your backend POSTs payloads to)
+
+### `listDistributors()` **(Linux / UnifiedPush only)**
+Lists every running UnifiedPush distributor by its D-Bus bus name (e.g. `org.unifiedpush.Distributor.ntfy`). Returns an empty array when none is installed — that's the signal to ask the user to install one from <https://unifiedpush.org/users/distributors/>.
+
+Throws on non-Linux platforms because the underlying Tauri command isn't registered there.
+
+**Returns:** `Promise<string[]>`
+
+### `setDistributor(name: string)` **(Linux / UnifiedPush only)**
+Pins the distributor used on the next `registerForPushNotifications()` call. **Must be called before `registerForPushNotifications()`** — calling it after a successful register has no effect on the existing endpoint; to switch distributors, unregister and register again.
 
-**Returns:** `Promise<string>` - The device push token
+The selection is **not persisted** across launches — if the host app wants to remember the user's choice, store it and re-apply on startup. If never called, the first entry from `listDistributors()` is used.
+
+Rejects if `name` isn't currently on the bus. Throws on non-Linux platforms.
+
+### `setToken(token: string)` **(Linux / UnifiedPush only)**
+Sets the UnifiedPush client token used on subsequent `registerForPushNotifications()` calls. **Must be called before `registerForPushNotifications()`** — calling it after a successful register has no effect on the existing endpoint.
+
+The endpoint URL the distributor returns is derived from `(app_identifier, client_token)`, so passing the same token across launches yields the same endpoint URL. The token is **not persisted** — the host app must store it and re-apply on startup if it wants endpoint stability.
+
+If never called, a fresh UUID is generated on each register call (FCM/APNs-style token rotation — the app pushes the new endpoint URL to its backend each time).
+
+Rejects if `token` is empty. Throws on non-Linux platforms.
 
 ### `sendNotification(options: Options | string)`
 Sends a notification to the user. Can be called with a simple string for the title or with a detailed options object.
@@ -558,6 +587,7 @@ Listens for notification action performed events.
 - Actions support varies by platform
 - Limited scheduling capabilities on some platforms
 - Channels not applicable (Android-specific)
+- Linux additionally supports server-driven push via UnifiedPush (see [Linux UnifiedPush Setup](#linux-unifiedpush-setup))
 
 ### iOS
 - Requires permission request
@@ -615,6 +645,70 @@ Listens for notification action performed events.
      ```
    - The notification plugin already includes the Firebase Cloud Messaging dependency when the `push-notifications` feature is enabled
 
+### Linux UnifiedPush Setup
+
+UnifiedPush is a federated push protocol where a user-installed *distributor* app delivers messages to your app over D-Bus. The plugin implements the *connector* side and exposes the standard `registerForPushNotifications()` flow.
+
+1. **Enable the `push-notifications` feature** in your `Cargo.toml` (this pulls in the `zbus` / `tokio` / `uuid` deps on Linux).
+2. **Install a distributor**. The user picks one (or you ship one with your app):
+   - [ntfy](https://ntfy.sh/) — minimal, self-hostable, has a Linux desktop client
+   - [NextPush](https://nextpush.unifiedpush.org/) — backed by a Nextcloud server
+   - [Conversations](https://conversations.im/) — XMPP-based
+   - Full list: <https://unifiedpush.org/users/distributors/>
+3. **Register from JS**:
+   ```typescript
+   import { registerForPushNotifications, listDistributors, setDistributor, setToken } from '@choochmeque/tauri-plugin-notifications-api';
+
+   const distributors = await listDistributors();
+   if (distributors.length === 0) {
+     // prompt the user to install a distributor
+     return;
+   }
+   await setDistributor(distributors[0]);
+   const storedToken = localStorage.getItem('up-client-token') ?? crypto.randomUUID();
+   localStorage.setItem('up-client-token', storedToken);
+   await setToken(storedToken);
+   const endpoint = await registerForPushNotifications();
+   // POST `endpoint` to your backend so it can deliver pushes
+   ```
+
+#### Receiving pushes while the app is running
+
+Incoming UnifiedPush messages are handled automatically:
+
+- A system toast is shown via `notify-rust` (if that feature is enabled — it is by default).
+- The same `onNotificationReceived` listener that handles local notifications fires with `source: "push"`:
+
+  ```typescript
+  import { onNotificationReceived } from '@choochmeque/tauri-plugin-notifications-api';
+
+  const unlisten = await onNotificationReceived((n) => {
+    if (n.source === 'push') {
+      console.log('UnifiedPush message:', n.title, n.body, n.extra);
+    }
+  });
+  ```
+
+The plugin best-effort-parses the message bytes as JSON and extracts `title`, `body` (or `message`), and `data` (or `extra`). Non-JSON payloads land in `body` as a plain string. Binary payloads end up in `extra` as a `<binary N bytes>` marker.
+
+#### Receiving pushes when the app is closed (optional)
+
+UnifiedPush delivers messages by D-Bus method call on the app's bus name. If the app isn't running when a push arrives, the distributor relies on D-Bus session activation to launch it.
+
+To enable that, ship a `.service` activation file at `~/.local/share/dbus-1/services/<app-identifier>.service`:
+
+```ini
+[D-BUS Service]
+Name=com.example.MyApp
+Exec=/usr/bin/my-app
+```
+
+Replace `Name` with your Tauri app's identifier (the `identifier` field from `tauri.conf.json`) and `Exec` with the absolute path to the installed binary. Without this file, pushes are only delivered while the app is already running.
+
+The plugin does **not** install this file for you — it's a packaging/deployment decision. Distros and packagers typically install it from the `.deb` / `.rpm` / Flatpak manifest.
+
+**Important caveat about cold-start delivery:** the plugin's UnifiedPush connector (the D-Bus service that owns your app identifier) is **lazily initialized** on the first call to `listDistributors()`, `setDistributor()`, `setToken()`, or `registerForPushNotifications()` from the JS layer. If your app is launched by D-Bus activation purely to handle a push, the distributor's method call may race the lazy init and arrive before the connector is registered — the call then fails silently. To make activation-driven delivery reliable, trigger the init eagerly in your Rust `setup()` (e.g. call `notifications.list_distributors()` once before returning), or call `listDistributors()` from JS as early as your app starts. Until you do, treat the `.service` activation as best-effort.
+
 ## Testing
 
 ### Desktop

package/dist-js/index.cjs

@@ -131,7 +131,21 @@ async function requestPermission() {
     return await core.invoke("plugin:notifications|request_permission");
 }
 /**
- * Registers the app for push notifications (mobile).
+ * Registers the app for push notifications.
+ *
+ * Returns a platform-dependent string identifying this push registration:
+ * - **iOS**: APNs device token
+ * - **Android**: Firebase Cloud Messaging token
+ * - **Linux**: UnifiedPush endpoint URL (the URL your backend POSTs payloads to).
+ *   The host app may persist this and treat it as the new endpoint on each
+ *   launch (FCM/APNs style), or call {@link setToken} beforehand with a
+ *   stored client token to receive the same endpoint URL across launches.
+ *
+ * On Linux this requires the `push-notifications` feature and at least one
+ * UnifiedPush distributor running on the system; see the README for setup.
+ * Any {@link setDistributor} or {@link setToken} calls must happen
+ * **before** this — they only affect the next register call, and once
+ * registered the endpoint URL is fixed until you unregister.
  *
  * @example
  * ```typescript
@@ -140,16 +154,17 @@ async function requestPermission() {
  * console.log('Push token:', token);
  * ```
  *
- * @returns A promise resolving to the device push token.
+ * @returns A promise resolving to the platform-specific push identifier.
  */
 async function registerForPushNotifications() {
     return await core.invoke("plugin:notifications|register_for_push_notifications");
 }
 /**
- * Unregisters the app from push notifications (mobile).
+ * Unregisters the app from push notifications.
  *
- * This removes the device's push notification token and stops receiving
- * remote push notifications.
+ * This removes the device's push notification registration and stops
+ * receiving remote pushes. On Linux it calls `Unregister` on the active
+ * UnifiedPush distributor.
  *
  * @example
  * ```typescript
@@ -161,7 +176,104 @@ async function registerForPushNotifications() {
  * @returns A promise resolving when unregistration is complete.
  */
 async function unregisterForPushNotifications() {
-    return await core.invoke("plugin:notifications|unregister_for_push_notifications");
+    await core.invoke("plugin:notifications|unregister_for_push_notifications");
+}
+/**
+ * Lists currently running UnifiedPush distributors by D-Bus bus name
+ * (e.g. `org.unifiedpush.Distributor.ntfy`).
+ *
+ * **Linux only, and only when the plugin was built with the
+ * `push-notifications` Rust feature** (the Tauri commands are gated behind
+ * `#[cfg(all(target_os = "linux", feature = "push-notifications"))]`).
+ * Throws elsewhere because the command isn't registered.
+ *
+ * Returns an empty array when no UnifiedPush distributor is installed —
+ * this is the signal to prompt the user to install one
+ * (https://unifiedpush.org/users/distributors/).
+ *
+ * @example
+ * ```typescript
+ * import { listDistributors } from '@choochmeque/tauri-plugin-notifications-api';
+ * const distributors = await listDistributors();
+ * if (distributors.length === 0) {
+ *   alert('Please install a UnifiedPush distributor');
+ * }
+ * ```
+ *
+ * @returns A promise resolving to the list of distributor bus names.
+ * @platform linux
+ */
+async function listDistributors() {
+    return await core.invoke("plugin:notifications|list_distributors");
+}
+/**
+ * Pins the UnifiedPush distributor used for the next
+ * {@link registerForPushNotifications} call.
+ *
+ * **Linux only, and only when the plugin was built with the
+ * `push-notifications` Rust feature.** Throws elsewhere because the
+ * underlying Tauri command isn't registered.
+ *
+ * **Must be called before {@link registerForPushNotifications}.** Calling
+ * this after a successful register has no effect on the existing endpoint
+ * — to switch distributors, unregister and register again.
+ *
+ * The selection lives only for the current process — it is **not persisted**
+ * across launches. If the host app wants to remember the user's choice, it
+ * must store the name itself and re-apply it via this function on startup.
+ * If never called, the first distributor returned by {@link listDistributors}
+ * is used.
+ *
+ * @example
+ * ```typescript
+ * import { setDistributor } from '@choochmeque/tauri-plugin-notifications-api';
+ * await setDistributor('org.unifiedpush.Distributor.ntfy');
+ * ```
+ *
+ * @param name The distributor bus name. Must be one of the values returned
+ *             by {@link listDistributors}; otherwise rejects.
+ * @platform linux
+ */
+async function setDistributor(name) {
+    await core.invoke("plugin:notifications|set_distributor", { name });
+}
+/**
+ * Sets the UnifiedPush client token used on subsequent
+ * {@link registerForPushNotifications} calls.
+ *
+ * **Linux only, and only when the plugin was built with the
+ * `push-notifications` Rust feature.** Throws elsewhere because the
+ * underlying Tauri command isn't registered.
+ *
+ * **Must be called before {@link registerForPushNotifications}.** Calling
+ * this after a successful register has no effect on the existing endpoint
+ * — to get a different endpoint URL, unregister and register again.
+ *
+ * UnifiedPush distributors derive the endpoint URL from
+ * `(connector_bus_name, client_token)`, so apps that want endpoint
+ * stability across launches should persist a token (any non-empty string,
+ * usually a UUID) and call this on startup before registering. If never
+ * called, a fresh UUID is generated on each register call and the endpoint
+ * URL will be unique per launch — the same model as FCM/APNs token
+ * rotation, where the app pushes the new token to its backend each time.
+ *
+ * The token lives only for the current process — it is **not persisted**
+ * across launches.
+ *
+ * @example
+ * ```typescript
+ * import { setToken, registerForPushNotifications } from '@choochmeque/tauri-plugin-notifications-api';
+ * const storedToken = localStorage.getItem('up-client-token') ?? crypto.randomUUID();
+ * localStorage.setItem('up-client-token', storedToken);
+ * await setToken(storedToken);
+ * const endpoint = await registerForPushNotifications();
+ * ```
+ *
+ * @param token The client token. Must be non-empty.
+ * @platform linux
+ */
+async function setToken(token) {
+    await core.invoke("plugin:notifications|set_token", { token });
 }
 /**
  * Sends a notification to the user.
@@ -290,7 +402,7 @@ async function removeActive(notifications) {
  * @returns A promise indicating the success or failure of the operation.
  */
 async function removeAllActive() {
-    await core.invoke("plugin:notifications|remove_active", { notifications: [] });
+    await core.invoke("plugin:notifications|remove_all");
 }
 /**
  * Creates a notification channel.
@@ -423,6 +535,7 @@ exports.cancelAll = cancelAll;
 exports.channels = channels;
 exports.createChannel = createChannel;
 exports.isPermissionGranted = isPermissionGranted;
+exports.listDistributors = listDistributors;
 exports.onAction = onAction;
 exports.onNotificationClicked = onNotificationClicked;
 exports.onNotificationReceived = onNotificationReceived;
@@ -434,4 +547,6 @@ exports.removeAllActive = removeAllActive;
 exports.removeChannel = removeChannel;
 exports.requestPermission = requestPermission;
 exports.sendNotification = sendNotification;
+exports.setDistributor = setDistributor;
+exports.setToken = setToken;
 exports.unregisterForPushNotifications = unregisterForPushNotifications;

package/dist-js/index.d.ts

@@ -381,7 +381,21 @@ declare function isPermissionGranted(): Promise<boolean>;
  */
 declare function requestPermission(): Promise<NotificationPermission>;
 /**
- * Registers the app for push notifications (mobile).
+ * Registers the app for push notifications.
+ *
+ * Returns a platform-dependent string identifying this push registration:
+ * - **iOS**: APNs device token
+ * - **Android**: Firebase Cloud Messaging token
+ * - **Linux**: UnifiedPush endpoint URL (the URL your backend POSTs payloads to).
+ *   The host app may persist this and treat it as the new endpoint on each
+ *   launch (FCM/APNs style), or call {@link setToken} beforehand with a
+ *   stored client token to receive the same endpoint URL across launches.
+ *
+ * On Linux this requires the `push-notifications` feature and at least one
+ * UnifiedPush distributor running on the system; see the README for setup.
+ * Any {@link setDistributor} or {@link setToken} calls must happen
+ * **before** this — they only affect the next register call, and once
+ * registered the endpoint URL is fixed until you unregister.
  *
  * @example
  * ```typescript
@@ -390,14 +404,15 @@ declare function requestPermission(): Promise<NotificationPermission>;
  * console.log('Push token:', token);
  * ```
  *
- * @returns A promise resolving to the device push token.
+ * @returns A promise resolving to the platform-specific push identifier.
  */
 declare function registerForPushNotifications(): Promise<string>;
 /**
- * Unregisters the app from push notifications (mobile).
+ * Unregisters the app from push notifications.
  *
- * This removes the device's push notification token and stops receiving
- * remote push notifications.
+ * This removes the device's push notification registration and stops
+ * receiving remote pushes. On Linux it calls `Unregister` on the active
+ * UnifiedPush distributor.
  *
  * @example
  * ```typescript
@@ -408,7 +423,98 @@ declare function registerForPushNotifications(): Promise<string>;
  *
  * @returns A promise resolving when unregistration is complete.
  */
-declare function unregisterForPushNotifications(): Promise<string>;
+declare function unregisterForPushNotifications(): Promise<void>;
+/**
+ * Lists currently running UnifiedPush distributors by D-Bus bus name
+ * (e.g. `org.unifiedpush.Distributor.ntfy`).
+ *
+ * **Linux only, and only when the plugin was built with the
+ * `push-notifications` Rust feature** (the Tauri commands are gated behind
+ * `#[cfg(all(target_os = "linux", feature = "push-notifications"))]`).
+ * Throws elsewhere because the command isn't registered.
+ *
+ * Returns an empty array when no UnifiedPush distributor is installed —
+ * this is the signal to prompt the user to install one
+ * (https://unifiedpush.org/users/distributors/).
+ *
+ * @example
+ * ```typescript
+ * import { listDistributors } from '@choochmeque/tauri-plugin-notifications-api';
+ * const distributors = await listDistributors();
+ * if (distributors.length === 0) {
+ *   alert('Please install a UnifiedPush distributor');
+ * }
+ * ```
+ *
+ * @returns A promise resolving to the list of distributor bus names.
+ * @platform linux
+ */
+declare function listDistributors(): Promise<string[]>;
+/**
+ * Pins the UnifiedPush distributor used for the next
+ * {@link registerForPushNotifications} call.
+ *
+ * **Linux only, and only when the plugin was built with the
+ * `push-notifications` Rust feature.** Throws elsewhere because the
+ * underlying Tauri command isn't registered.
+ *
+ * **Must be called before {@link registerForPushNotifications}.** Calling
+ * this after a successful register has no effect on the existing endpoint
+ * — to switch distributors, unregister and register again.
+ *
+ * The selection lives only for the current process — it is **not persisted**
+ * across launches. If the host app wants to remember the user's choice, it
+ * must store the name itself and re-apply it via this function on startup.
+ * If never called, the first distributor returned by {@link listDistributors}
+ * is used.
+ *
+ * @example
+ * ```typescript
+ * import { setDistributor } from '@choochmeque/tauri-plugin-notifications-api';
+ * await setDistributor('org.unifiedpush.Distributor.ntfy');
+ * ```
+ *
+ * @param name The distributor bus name. Must be one of the values returned
+ *             by {@link listDistributors}; otherwise rejects.
+ * @platform linux
+ */
+declare function setDistributor(name: string): Promise<void>;
+/**
+ * Sets the UnifiedPush client token used on subsequent
+ * {@link registerForPushNotifications} calls.
+ *
+ * **Linux only, and only when the plugin was built with the
+ * `push-notifications` Rust feature.** Throws elsewhere because the
+ * underlying Tauri command isn't registered.
+ *
+ * **Must be called before {@link registerForPushNotifications}.** Calling
+ * this after a successful register has no effect on the existing endpoint
+ * — to get a different endpoint URL, unregister and register again.
+ *
+ * UnifiedPush distributors derive the endpoint URL from
+ * `(connector_bus_name, client_token)`, so apps that want endpoint
+ * stability across launches should persist a token (any non-empty string,
+ * usually a UUID) and call this on startup before registering. If never
+ * called, a fresh UUID is generated on each register call and the endpoint
+ * URL will be unique per launch — the same model as FCM/APNs token
+ * rotation, where the app pushes the new token to its backend each time.
+ *
+ * The token lives only for the current process — it is **not persisted**
+ * across launches.
+ *
+ * @example
+ * ```typescript
+ * import { setToken, registerForPushNotifications } from '@choochmeque/tauri-plugin-notifications-api';
+ * const storedToken = localStorage.getItem('up-client-token') ?? crypto.randomUUID();
+ * localStorage.setItem('up-client-token', storedToken);
+ * await setToken(storedToken);
+ * const endpoint = await registerForPushNotifications();
+ * ```
+ *
+ * @param token The client token. Must be non-empty.
+ * @platform linux
+ */
+declare function setToken(token: string): Promise<void>;
 /**
  * Sends a notification to the user.
  * @example
@@ -627,4 +733,4 @@ interface NotificationClickedData {
  */
 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, };
+export { Importance, Visibility, sendNotification, requestPermission, isPermissionGranted, registerForPushNotifications, unregisterForPushNotifications, listDistributors, setDistributor, setToken, registerActionTypes, pending, cancel, cancelAll, active, removeActive, removeAllActive, createChannel, removeChannel, channels, onNotificationReceived, onAction, onNotificationClicked, Schedule, ScheduleEvery, };

package/dist-js/index.js

@@ -129,7 +129,21 @@ async function requestPermission() {
     return await invoke("plugin:notifications|request_permission");
 }
 /**
- * Registers the app for push notifications (mobile).
+ * Registers the app for push notifications.
+ *
+ * Returns a platform-dependent string identifying this push registration:
+ * - **iOS**: APNs device token
+ * - **Android**: Firebase Cloud Messaging token
+ * - **Linux**: UnifiedPush endpoint URL (the URL your backend POSTs payloads to).
+ *   The host app may persist this and treat it as the new endpoint on each
+ *   launch (FCM/APNs style), or call {@link setToken} beforehand with a
+ *   stored client token to receive the same endpoint URL across launches.
+ *
+ * On Linux this requires the `push-notifications` feature and at least one
+ * UnifiedPush distributor running on the system; see the README for setup.
+ * Any {@link setDistributor} or {@link setToken} calls must happen
+ * **before** this — they only affect the next register call, and once
+ * registered the endpoint URL is fixed until you unregister.
  *
  * @example
  * ```typescript
@@ -138,16 +152,17 @@ async function requestPermission() {
  * console.log('Push token:', token);
  * ```
  *
- * @returns A promise resolving to the device push token.
+ * @returns A promise resolving to the platform-specific push identifier.
  */
 async function registerForPushNotifications() {
     return await invoke("plugin:notifications|register_for_push_notifications");
 }
 /**
- * Unregisters the app from push notifications (mobile).
+ * Unregisters the app from push notifications.
  *
- * This removes the device's push notification token and stops receiving
- * remote push notifications.
+ * This removes the device's push notification registration and stops
+ * receiving remote pushes. On Linux it calls `Unregister` on the active
+ * UnifiedPush distributor.
  *
  * @example
  * ```typescript
@@ -159,7 +174,104 @@ async function registerForPushNotifications() {
  * @returns A promise resolving when unregistration is complete.
  */
 async function unregisterForPushNotifications() {
-    return await invoke("plugin:notifications|unregister_for_push_notifications");
+    await invoke("plugin:notifications|unregister_for_push_notifications");
+}
+/**
+ * Lists currently running UnifiedPush distributors by D-Bus bus name
+ * (e.g. `org.unifiedpush.Distributor.ntfy`).
+ *
+ * **Linux only, and only when the plugin was built with the
+ * `push-notifications` Rust feature** (the Tauri commands are gated behind
+ * `#[cfg(all(target_os = "linux", feature = "push-notifications"))]`).
+ * Throws elsewhere because the command isn't registered.
+ *
+ * Returns an empty array when no UnifiedPush distributor is installed —
+ * this is the signal to prompt the user to install one
+ * (https://unifiedpush.org/users/distributors/).
+ *
+ * @example
+ * ```typescript
+ * import { listDistributors } from '@choochmeque/tauri-plugin-notifications-api';
+ * const distributors = await listDistributors();
+ * if (distributors.length === 0) {
+ *   alert('Please install a UnifiedPush distributor');
+ * }
+ * ```
+ *
+ * @returns A promise resolving to the list of distributor bus names.
+ * @platform linux
+ */
+async function listDistributors() {
+    return await invoke("plugin:notifications|list_distributors");
+}
+/**
+ * Pins the UnifiedPush distributor used for the next
+ * {@link registerForPushNotifications} call.
+ *
+ * **Linux only, and only when the plugin was built with the
+ * `push-notifications` Rust feature.** Throws elsewhere because the
+ * underlying Tauri command isn't registered.
+ *
+ * **Must be called before {@link registerForPushNotifications}.** Calling
+ * this after a successful register has no effect on the existing endpoint
+ * — to switch distributors, unregister and register again.
+ *
+ * The selection lives only for the current process — it is **not persisted**
+ * across launches. If the host app wants to remember the user's choice, it
+ * must store the name itself and re-apply it via this function on startup.
+ * If never called, the first distributor returned by {@link listDistributors}
+ * is used.
+ *
+ * @example
+ * ```typescript
+ * import { setDistributor } from '@choochmeque/tauri-plugin-notifications-api';
+ * await setDistributor('org.unifiedpush.Distributor.ntfy');
+ * ```
+ *
+ * @param name The distributor bus name. Must be one of the values returned
+ *             by {@link listDistributors}; otherwise rejects.
+ * @platform linux
+ */
+async function setDistributor(name) {
+    await invoke("plugin:notifications|set_distributor", { name });
+}
+/**
+ * Sets the UnifiedPush client token used on subsequent
+ * {@link registerForPushNotifications} calls.
+ *
+ * **Linux only, and only when the plugin was built with the
+ * `push-notifications` Rust feature.** Throws elsewhere because the
+ * underlying Tauri command isn't registered.
+ *
+ * **Must be called before {@link registerForPushNotifications}.** Calling
+ * this after a successful register has no effect on the existing endpoint
+ * — to get a different endpoint URL, unregister and register again.
+ *
+ * UnifiedPush distributors derive the endpoint URL from
+ * `(connector_bus_name, client_token)`, so apps that want endpoint
+ * stability across launches should persist a token (any non-empty string,
+ * usually a UUID) and call this on startup before registering. If never
+ * called, a fresh UUID is generated on each register call and the endpoint
+ * URL will be unique per launch — the same model as FCM/APNs token
+ * rotation, where the app pushes the new token to its backend each time.
+ *
+ * The token lives only for the current process — it is **not persisted**
+ * across launches.
+ *
+ * @example
+ * ```typescript
+ * import { setToken, registerForPushNotifications } from '@choochmeque/tauri-plugin-notifications-api';
+ * const storedToken = localStorage.getItem('up-client-token') ?? crypto.randomUUID();
+ * localStorage.setItem('up-client-token', storedToken);
+ * await setToken(storedToken);
+ * const endpoint = await registerForPushNotifications();
+ * ```
+ *
+ * @param token The client token. Must be non-empty.
+ * @platform linux
+ */
+async function setToken(token) {
+    await invoke("plugin:notifications|set_token", { token });
 }
 /**
  * Sends a notification to the user.
@@ -288,7 +400,7 @@ async function removeActive(notifications) {
  * @returns A promise indicating the success or failure of the operation.
  */
 async function removeAllActive() {
-    await invoke("plugin:notifications|remove_active", { notifications: [] });
+    await invoke("plugin:notifications|remove_all");
 }
 /**
  * Creates a notification channel.
@@ -414,4 +526,4 @@ async function onNotificationClicked(cb) {
     };
 }
 
-export { Importance, Schedule, ScheduleEvery, Visibility, active, cancel, cancelAll, channels, createChannel, isPermissionGranted, onAction, onNotificationClicked, onNotificationReceived, pending, registerActionTypes, registerForPushNotifications, removeActive, removeAllActive, removeChannel, requestPermission, sendNotification, unregisterForPushNotifications };
+export { Importance, Schedule, ScheduleEvery, Visibility, active, cancel, cancelAll, channels, createChannel, isPermissionGranted, listDistributors, onAction, onNotificationClicked, onNotificationReceived, pending, registerActionTypes, registerForPushNotifications, removeActive, removeAllActive, removeChannel, requestPermission, sendNotification, setDistributor, setToken, unregisterForPushNotifications };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choochmeque/tauri-plugin-notifications-api",
-  "version": "0.4.5",
+  "version": "0.5.0-rc.3",
   "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.",