feat(notification): add plugin (#326)

2026-07-24 17:20:51 +02:00 · 2023-05-02 09:09:50 -07:00
parent 864b9d790f
commit e9bbe94181
34 changed files with 1536 additions and 8 deletions
@@ -0,0 +1,113 @@
+// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+/**
+ * Send toast notifications (brief auto-expiring OS window element) to your user.
+ * Can also be used with the Notification Web API.
+ *
+ * This package is also accessible with `window.__TAURI__.notification` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
+ *
+ * The APIs must be added to [`tauri.allowlist.notification`](https://tauri.app/v1/api/config/#allowlistconfig.notification) in `tauri.conf.json`:
+ * ```json
+ * {
+ *   "tauri": {
+ *     "allowlist": {
+ *       "notification": {
+ *         "all": true // enable all notification APIs
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * It is recommended to allowlist only the APIs you use for optimal bundle size and security.
+ * @module
+ */
+
+import { invoke } from '@tauri-apps/api/tauri'
+
+/**
+ * Options to send a notification.
+ *
+ * @since 1.0.0
+ */
+interface Options {
+  /** Notification title. */
+  title: string
+  /** Optional notification body. */
+  body?: string
+  /** Optional notification icon. */
+  icon?: string
+}
+
+/** Possible permission values. */
+type Permission = 'granted' | 'denied' | 'default'
+
+/**
+ * Checks if the permission to send notifications is granted.
+ * @example
+ * ```typescript
+ * import { isPermissionGranted } from '@tauri-apps/api/notification';
+ * const permissionGranted = await isPermissionGranted();
+ * ```
+ *
+ * @since 1.0.0
+ */
+async function isPermissionGranted(): Promise<boolean> {
+  if (window.Notification.permission !== 'default') {
+    return Promise.resolve(window.Notification.permission === 'granted')
+  }
+  return invoke('plugin:notification|is_permission_granted')
+}
+
+/**
+ * Requests the permission to send notifications.
+ * @example
+ * ```typescript
+ * import { isPermissionGranted, requestPermission } from '@tauri-apps/api/notification';
+ * let permissionGranted = await isPermissionGranted();
+ * if (!permissionGranted) {
+ *   const permission = await requestPermission();
+ *   permissionGranted = permission === 'granted';
+ * }
+ * ```
+ *
+ * @returns A promise resolving to whether the user granted the permission or not.
+ *
+ * @since 1.0.0
+ */
+async function requestPermission(): Promise<Permission> {
+  return window.Notification.requestPermission()
+}
+
+/**
+ * Sends a notification to the user.
+ * @example
+ * ```typescript
+ * import { isPermissionGranted, requestPermission, sendNotification } from '@tauri-apps/api/notification';
+ * let permissionGranted = await isPermissionGranted();
+ * if (!permissionGranted) {
+ *   const permission = await requestPermission();
+ *   permissionGranted = permission === 'granted';
+ * }
+ * if (permissionGranted) {
+ *   sendNotification('Tauri is awesome!');
+ *   sendNotification({ title: 'TAURI', body: 'Tauri is awesome!' });
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+function sendNotification(options: Options | string): void {
+  if (typeof options === 'string') {
+    // eslint-disable-next-line no-new
+    new window.Notification(options)
+  } else {
+    // eslint-disable-next-line no-new
+    new window.Notification(options.title, options)
+  }
+}
+
+export type { Options, Permission }
+
+export { sendNotification, requestPermission, isPermissionGranted }