powertoast

About
=====

Windows toast notification and toastXml string builder.

Doesn't use any native module. Everything is done through PowerShell but you can use native WinRT API bindings instead by optionally installing NodeRT relative packages (see installation for more details).

Please note that when using PowerShell some features such as click events and user input requires Powershell ≥ 7.1 (pwsh) also known as PowerShell Core.

Using WinRT (NodeRT) is a bit faster as you don't have to wait for the PowerShell VM to start.

Electron

Powertoast was made for Node.js first but it also works in Electron with either PowerShell or WinRT (NodeRT).

If you prefer to use the new Electron native API directly.
You can easily build a toastXml string for it.

Example
=======

$3

``js
import { Toast } from "powertoast";

//Create a toast
const toast = new Toast({
title: "NPM",
message: "Installed.",
icon: "https://static.npmjs.com/7a7ffabbd910fc60161bc04f2cee4160.png"
})

//Events (optional)
toast.on("activated", (event, input) => {
// Where event and input are the data from an interactive toast
console.log("click");
});
toast.on("dismissed", (reason) => { console.log(reason) });

toast.show() //Promise
.then(()=>{
console.log("Sent");
})
.catch((err) => {
console.error(err);
});
`

$3

`js
//Main process
import { Notification } from "electron";
import { toXmlString } from "powertoast";

const options = {
title: "First partner",
message: "Every journey begins with a choice",
button: [
{ text: "Bulbasaur", activation: "myapp:green" },
{ text: "Charmander", activation: "myapp:red" },
{ text: "Squirtle", activation: "myapp:blue" }
]
};

const xmlString = toXmlString(options);
const toast = new Notification({ toastXml: xmlString });
toast.show();
`

Installation
============

`
npm install powertoast
`

API
===

⚠️ This module is only available as an ECMAScript module (ESM) starting with version 2.0.0.

Previous version(s) are CommonJS (CJS) with an ESM wrapper.

ℹ️ Windows 8/8.1 support was removed in 3.x

Named export

$3

Create a toast notification.

_extends 📖 EventEmitter_

#### Constructor

(option?: object)

ℹ️ Because there is a ton of options for toast notification, they are in TOAST.md.

#### Events

- activated (event: string, input: { key: value, ... })

When user activates a toast notification through a click.

Event is the argument passed by the notification or button.

Input (textbox and/or selection) is the user input represented as key/value pair(s).

- dismissed (reason: string)

When a toast notification leaves the screen, either by expiring or being explicitly dismissed by the user.

|Name|Description|
|----|-----------|
|UserCanceled|User dismissed the toast|
|ApplicationHidden|Application explicitly hid the toast|
|TimedOut|Toast had been shown for the maximum allowed time and was faded out|

#### Methods

- clear(): Promise

Remove the notification from the notification center and all event listeners.

- show(option?: object): Promise

Show toast notification.

⚙️ Options

+ disableWinRT?: boolean (false)

If you have installed the optional NodeRT native module(s) but for whatever reason(s) you want to use PowerShell instead set this to true.

+ disablePowershellCore?: boolean (false)

By default when using PowerShell this module will first try to use pwsh (PowerShell Core), then powershell (PowerShell Desktop / Windows Embedded).
Set this to true to skip pwsh and only use powershell which is included with Windows.

ℹ️ PowerShell Core has some caveats hence the option to disable/skip it:

- It's painfully slow to start.
- It needs to be installed and its path added to your env var.
- In order for PowerShell Core to use WinRT it will have to download WinRT assemblies
through its package manager (done on first run).

⚠️ Please note that some features such as click events and user input requires Powershell ≥ 7.1 (pwsh).


+ keepalive?: number (6) seconds

⚠️ This option is only for when listening for events !

The maximum amount of time PowerShell will wait for events before exiting or how long to keep the event loop alive for NodeRT.

PowerShell needs to be running to subscribe to the events and NodeRT registered event listener does not keep the event loop alive.
The default value is 6 seconds as 5 seconds is the default notification duration but keep in mind some users might have change this value in their Windows settings.

ℹ️ NB: When using NodeRT If you have something else maintaining the event loop then you can ignore this.

Returns

✔️ Resolves as soon as the notification has been dispatched. Except when PowerShell needs to be running to subscribe to events in which case the promise will resolve only afterwards.

❌ Rejects on error.



$3

Expose the toastXML string builder used by the Toast class for debugging purposes or for example if you want to use it with Electron native API.

Please see the Toast class constructor for the relevant options.

ℹ️ The following options have no effect when just building a Toast XmlString:

- aumid
- uniqueID
- hide
- sequenceNumber
- expiration

$3

True if the peerDependencies for WinRT were successfully loaded; false otherwise.

$3

Remove programmatically notification(s) from the notification center.

If using only aumid then it removes every notification for said aumid in the notification center.

If you provide an optional uniqueID (string) then it removes that specific notification for the given aumid.

ℹ️ This library uniqueID option actually sets both tag and groupLabel to the same value for convenience.

If you want to use the tag and groupLabel properties of a toast to target a notification then use

uniqueID (array) as [ groupLabel: string, tag?: string ].

$3

List the current notification(s) for the given aumid in the notification center.

📖 Microsoft doc
=================

📖 Microsoft Toast API.

📖 Toast content XML schema.

📖 ToastNotificationHistory class.

📖 ToastNotification properties.

📖 send-local-toast-other-apps.