Node-dbus-notifier NPM

node-dbus-notifier

A DBus-based NodeJS library for desktop notifications.

Use the DBus interface org.freedesktop.Notifications to create notifications instead of using notify-send, making it possible to provide full-featured support for desktop notifications on Linux (or any DBus-enabled system) and conform to the Desktop Notifications Specification.

Implementation Specification Version: 1.2

Install

Using npm: npm install node-dbus-notifier --save
or
Using yarn: yarn add node-dbus-notifier

Examples

Make sure your current system supports DBus and has a provider that conforms to the Desktop Notifications Specification before using it.

simple notification

const { Notify } = require('node-dbus-notifier');

const notify = new Notify({
  appName: 'My App',
  summary: 'This is summary',
  body: 'This is body',
  timeout: 3000,
});

notify.show()
  .then((result) => {
    console.log(`notify is closed: ${JSON.stringify(result)}`);
  });

Notification with button and icon

const { Notify } = require('node-dbus-notifier');

const notify = new Notify({
  appName: 'My App',
  appIcon: 'application-javascript', // The availability of icons depends on the current system icon set.
  summary: 'This is summary',
  body: 'This is body',
  timeout: 3000,
});

notify.addAction('Click Me', () => {
  console.log('Click Click');
});

notify.show();

Notification with custom image

const { Notify } = require('node-dbus-notifier');

const notify = new Notify({
  appName: 'My App',
  summary: 'This is summary',
  body: 'This is body',
  hints: {
    imagePath: '/path/to/image',
  },
  timeout: 3000,
});

notify.show();

See the DBus protocol of the Desktop Notifications Specification for more information.

Usage

The node-dbus-notifier creates a DBus session by default when the first notification is displayed and disconnects the DBus session when there are no notifications; if the session is not disconnected, the app will not exit properly.
If an external DBus session or interface is set, it will not auto disconnect the DBus session.

Supported non-standard specification actions

inline-reply: Add inline reply input box to the notification, the first parameter of the callback function is the submitted message.

`Notify`

constructor(config: Partial<NotifyConfig>): Initialize a notification, accepting the same parameters as org.freedesktop.Notifications.Notify, except for actions (using addAction()). hints does not support attributes marked as "Deprecated".
addAction(text: string, callback: () => void): string: Add an action to the notification with random action key, return action key.
addAction(text: string, key: string, callback: () => void): string: Add an action to notification with custom action key, return action key.
close(): void: Use org.freedesktop.Notifications.CloseNotification actively close notification.
removeAction(key: string): boolean: Use action key remove an added action
removeDefaultAction(): boolean : Alias for removeAction("default").
setDefaultAction(callback: () => void): void : Alias for addAction("", "default", callback). (The 'Default' action trigger is the click notification.)
show(): Use org.freedesktop.Notifications.Notify to display the notification and mark the Promise as resolved when the notification is dismissed.
event: close: Notification is closed
event: show: Notification is displayed
static supportedCapabilities(): Promise<string[]>: The capabilities supported by the notification server.

`Config: ConfigInterface`

autoDisconnectSessionBus: If set to false, the internal DBus session will not be automatically disconnected. Defaults to true, if there is no notification, the internal DBus session will be automatically disconnected.

`disconnectSessionBus(): void`

Disconnect the internal DBus session.

You shouldn't use it anywhere unless you set Config.autoDisconnectSessionBus to false or need to exit the app immediately.

`getInterface(): ClientInterface`

Get DBus interface org.freedesktop.Notifications.

If the interface is set from outside, it will return the external interface.

if you want to do something

`setInterface(notificationInterface?: ClientInterface): void`

Set DBus interface org.freedesktop.Notifications.

Set up an org.freedesktop.Notifications interface externally if you want to share an existing DBus interface.

If no arguments are passed, the internal interface will be reused.

`getSessionBus(): MessageBus`

Get DBus Session.

If the session is set from outside, it will return the external session.

if you want to do something

`setSessionBus(sessionBus?: MessageBus): void`

Set DBus session.

Set up an DBus session externally if you want to share an existing DBus session.

If no arguments are passed, the internal session will be reused.

I don't recommend you use getInterface() or getSessionBus() anywhere, they are actually created more for internal code and exporting them is just for special cases.