Powertoast

https://github.com/xan105/node-powertoast
Admin
Powertoast is a library for Windows toast notifications, providing a toastXml string builder and...
Tokens:6,515
Snippets:76
Trust Score:8.5
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Powertoast Package

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Standard npm command to install the powertoast package.

```bash
npm install powertoast
```

--------------------------------

### Toast with Buttons and Event Handling

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Demonstrates how to create a toast notification with multiple buttons and attach event listeners for activation and dismissal. This example shows basic button configuration with activation URLs.

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

const toast = new Toast({
  title: "Browser",
  message: "Choose your favorite",
  button: [
    { 
      text: "Firefox", 
      activation:"https://www.mozilla.org/en-US/firefox/new/"
    },
    { 
      text: "Chrome", 
      activation:"https://www.google.com/chrome/"
    }
  ]
});

t oast.on("activated", (event) => {
  console.log("clicked");
  console.log(url: event)
})
.on("dismissed", (reason) => {
  console.log("dismissed:", reason);
});

t oast.show()
.catch(console.error);
```

--------------------------------

### Create Custom Windows Sound Schema

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

This example shows how to create a custom sound schema in the Windows Registry to use a custom WAV file for toast notifications. This is a workaround for the limitation of not being able to use direct file paths for audio.

```plaintext
Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\AppEvents\Schemes\Apps\.Default\mysound]

[HKEY_CURRENT_USER\AppEvents\Schemes\Apps\.Default\mysound\.Current]
@="path_to_your_sound_file.wav"

[HKEY_CURRENT_USER\AppEvents\Schemes\Apps\.Default\mysound\.Default]
@="path_to_your_sound_file.wav"
```

--------------------------------

### Install NodeRT Packages with Specific Modules

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Use this command to install NodeRT packages with specific Windows SDK modules. This is useful for enabling advanced features like user input in toast notifications.

```bash
npm i @xan105/nodert --modules="windows.ui.notifications, windows.data.xml.dom, windows.foundation, windows.foundation.collections"
```

--------------------------------

### Toast with Custom URI Activation

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Uses a custom URI scheme for toast activation. This example demonstrates how to trigger a custom protocol from a notification.

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

const toast = new Toast({
  message: "custom URI",
  onClick: "electronApp:helloworld"
});

tost.show()
.catch(console.error);
```

--------------------------------

### Install NodeRT for Electron

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Install NodeRT packages specifically for Electron projects by including the `--electron` flag. This ensures compatibility with Electron's ABI.

```bash
npm i @xan105/nodert --electron --modules="windows.ui.notifications, windows.data.xml.dom"
```

--------------------------------

### Configure NodeRT Modules in package.json

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Add a `_nodert` section to your package.json to specify NodeRT modules that should be installed. This provides an alternative to using the command-line `--modules` flag.

```json
{
  "_nodert" : {
    "modules" : [
      "windows.data.xml.dom",
      "windows.ui.notifications"
    ]
  },
}
```

--------------------------------

### Toast with HTTP Activation

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Opens a specified URL in the default browser when the toast is clicked. Shows how to launch an external resource.

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

const toast = new Toast({
  message: "Google It",
  activation: "https://www.google.com"
});

tost.show()
.catch(console.error);
```

--------------------------------

### Create and Show a Simple Toast

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Use this snippet to create a basic toast notification with a title, message, and icon. It also demonstrates how to handle activation and dismissal events. The show() method returns a Promise.

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

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

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

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

--------------------------------

### Show a basic toast notification

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Demonstrates how to display a simple toast notification using the Toast class. Ensure the Toast class is imported before use.

```javascript
import { Toast } from "node-powertoast";

const toast = new Toast();
try {
  await toast.show({
    title: "Hello",
    message: "World"
  });
} catch (err) {
  // Handle error
}
```

--------------------------------

### Show a toast with custom options

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Illustrates how to show a toast notification with advanced options like disabling PowerShell Core. This is useful when you need specific PowerShell execution behavior.

```javascript
import { Toast } from "node-powertoast";

const toast = new Toast();
try {
  await toast.show({
    title: "Hello",
    message: "World",
    disablePowershellCore: true
  });
} catch (err) {
  // Handle error
}
```

--------------------------------

### Check for WinRT availability

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Demonstrates how to check if the necessary WinRT dependencies are available in the environment. This is a boolean flag that indicates whether WinRT can be used.

```javascript
import { isWinRTAvailable } from "node-powertoast";

if (isWinRTAvailable) {
  console.log("WinRT is available.");
} else {
  console.log("WinRT is not available.");
}
```

--------------------------------

### Electron App Single Instance Handling

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Configures an Electron app to handle single instance requests and parse arguments from custom URI schemes, such as those launched by toasts.

```javascript
if (app.requestSingleInstanceLock() !== true) app.exit();
app.on("second-instance", (event, argv, cwd) => {  
  console.log(argv);
  //[...,"electronApp:helloworld"]
});
```

--------------------------------

### Generate Toast XML string

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Shows how to use the `toXmlString` method to generate the XML representation of a toast notification. This can be useful for debugging or integration with other systems like Electron.

```javascript
import { Toast } from "node-powertoast";

const toast = new Toast();
const xmlString = toast.toXmlString({
  title: "Hello",
  message: "World"
});

console.log(xmlString);
```

--------------------------------

### Show Toast Notification with Attribution

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Demonstrates how to create and display a toast notification with a title, message, icon, and attribution text. Requires importing the Toast class from 'powertoast'.

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

const toast = new Toast({
    aumid: "com.squirrel.GitHubDesktop.GitHubDesktop",
    title: "Github",
    message: "Someone commented your issue",
    icon: "D:\\Desktop\\github.png",
    attribution: "Via Web"
});

tost.show()
.catch(console.error);
```

--------------------------------

### Build Toast XML for Electron Native API

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

This snippet shows how to generate a toast XML string using `toXmlString` for use with Electron's native Notification API. It includes options for title, message, and interactive buttons with activation arguments.

```javascript
//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 });
toa st.show();
```

--------------------------------

### Toast with Protocol Activation

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Opens the Windows Maps app with a pre-populated search query when the toast is clicked. Handles 'activated' and 'dismissed' events.

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

const toast = new Toast({
  message: "Sushi",
  activation: "bingmaps:?q=sushi"
});

tost.on("activated", (event) => {
  console.log("clicked");
  console.log(event) //"bingmaps:?q=sushi"
})
.on("dismissed", (reason) => {
  console.log("dismissed:", reason);
});

tost.show()
.catch(console.error);
```

--------------------------------

### isWinRTAvailable Constant

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

A boolean indicating whether the WinRT peer dependencies were successfully loaded.

```APIDOC
## isWinRTAvailable: boolean

### Description

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

--------------------------------

### toXmlString Method

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Exposes the toastXML string builder for debugging or use with other platforms like Electron.

```APIDOC
## toXmlString(option?: object): string

### Description

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](https://www.electronjs.org/fr/docs/latest/api/notification#new-notificationoptions).

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
```

--------------------------------

### Handle toast activation event

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Shows how to subscribe to the 'activated' event of a toast notification to perform actions when a user interacts with it. The event handler receives the event data and user input.

```javascript
import { Toast } from "node-powertoast";

const toast = new Toast();
try {
  await toast.show({
    title: "Hello",
    message: "World",
    actions: [
      {
        name: "Click Me",
        type: "button",
        arguments: "clicked"
      }
    ]
  });

  toast.on("activated", (event, input) => {
    console.log(event);
    console.log(input);
  });
} catch (err) {
  // Handle error
}
```

--------------------------------

### Select Object Structure

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Defines the structure for selection menus in PowerToast notifications. Use for predefined choices.

```typescript
{
  id: string,
  title?: string,
  items: [
    {
      id: string,
      text: string,
      default?: boolean
    }
  ]
}
```

--------------------------------

### Configure Toast Notification with AUMID

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Use this snippet to create a toast notification and specify a custom AUMID for either a UWP or Win32 application. Ensure the AUMID is valid for the target application.

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

const toast = new Toast({
  aumid: "Microsoft.XboxApp_8wekyb3d8bbwe!Microsoft.XboxApp", //Xbox App (UWP)
  aumid: "com.squirrel.GitHubDesktop.GitHubDesktop", //GitHub Desktop (win32)
  title: "Hello",
  message: "world"
});

tost.show()
.catch(console.error);
```

--------------------------------

### Handle toast dismissal event

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Demonstrates how to listen for the 'dismissed' event to know when a toast notification is no longer visible. The handler receives the reason for dismissal.

```javascript
import { Toast } from "node-powertoast";

const toast = new Toast();
try {
  await toast.show({
    title: "Hello",
    message: "World"
  });

  toast.on("dismissed", (reason) => {
    console.log(reason);
  });
} catch (err) {
  // Handle error
}
```

--------------------------------

### Button Object Structure

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Defines the properties available for creating a button in a toast notification. This includes text, activation details, icons, context menu options, tooltips, styling, and ID mapping.

```typescript
{
  text?: string,
  activation?: string | {
    type?: string,
    launch?: string,
    pfn?: string,
    behavior?: string,
  },
  icon?: string,
  contextMenu?: string,
  tooltip?: string,
  style?: string,
  id?: string
}
```

--------------------------------

### getHistory

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Lists the current notification(s) for a given aumid in the notification center. Optionally, verbose mode can be enabled to include additional properties.

```APIDOC
## getHistory

### Description
Retrieves the current notification(s) for a specified `aumid` from the notification center. The `verbose` option can be used to include additional details about each notification.

### Method
`getHistory(aumid: string, verbose?: boolean): Promise<object[]>``

### Parameters
#### Path Parameters
- **aumid** (string) - Required - The unique identifier for the application.
- **verbose** (boolean) - Optional - If true, includes additional properties in the response.

### Response
#### Success Response
Returns a Promise that resolves to an array of notification objects. Each object contains the following properties:
- **expirationTime** (string) - The time after which a toast should not be displayed.
- **tag** (string) - A unique identifier for the notification.
- **group** (string) - A unique identifier for the group label.

If `verbose` is true, the following properties are also included:
- **remoteID** (string or null) - An ID to correlate this notification with another one generated on another device.
- **suppressPopup** (boolean) - Whether the toast's pop-up UI is displayed on the user's screen.
- **mirroringAllowed** (boolean) - Whether the notification is allowed to be displayed on multiple devices.
- **expiresOnReboot** (boolean) - Whether the toast will remain in the notification center after a reboot.
- **highPriority** (boolean) - Whether the notification is displayed in high priority.
- **status** (string or null) - Additional information about the status of the toast.

### Response Example
```json
[
  {
    "expirationTime": "01/08/2021 20:53:23 +07:00",
    "tag": "unique-tag-1",
    "group": "app-group-1",
    "remoteID": "remote-123",
    "suppressPopup": false,
    "mirroringAllowed": true,
    "expiresOnReboot": false,
    "highPriority": true,
    "status": "processed"
  }
]
```
```

--------------------------------

### Toast Class

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Represents a toast notification. It extends EventEmitter and provides methods to create, show, and manage notifications.

```APIDOC
## Toast Class

### Description

Create a toast notification. Extends EventEmitter.

### Constructor

`(option?: object)`

Options for the toast notification are detailed in [TOAST.md](./TOAST.md).

### Events

- **activated** (event: string, input: { key: value, ... })
  Emitted when a user activates a toast notification through a click.
  - `event`: The argument passed by the notification or button.
  - `input`: User input represented as key/value pair(s).

- **dismissed** (reason: string)
  Emitted when a toast notification leaves the screen.
  - `reason`: Can be 'UserCanceled', 'ApplicationHidden', or 'TimedOut'.

### Methods

- **clear()**: `Promise<void>`
  Remove the notification from the notification center and all event listeners.

- **show(option?: object)**: `Promise<void>`
  Show toast notification.

  #### Options

  - **disableWinRT** (`boolean`, default: `false`): If true, uses PowerShell instead of NodeRT native modules.
  - **disablePowershellCore** (`boolean`, default: `false`): If true, skips pwsh and only uses powershell.
  - **keepalive** (`number`, default: `6` seconds): Maximum time PowerShell waits for events or how long to keep the event loop alive for NodeRT. Only relevant when listening for events.

  #### Returns

  Resolves when the notification has been dispatched. Rejects on error.
```

--------------------------------

### Toast Notification with Progress Bar

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Use this snippet to display a toast notification with a progress bar. Configure the progress bar's title, current value, an optional value override string, and a status message. Requires the 'powertoast' library.

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

const toast = new Toast({
  title: "Downloading your weekly playlist...",
  progress: {
    title: "Weekly playlist",
    value: 60,
    valueOverride: "15/26 songs",
    status: "Downloading..."
  }
});
  
tost.show()
.catch(console.error);
```

--------------------------------

### Input Object Structure

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Defines the structure for input text boxes in PowerToast notifications. Use for user data entry.

```typescript
{
  id: string,
  title?: string,
  placeholder?: string,
  value?: string
}
```

--------------------------------

### Play Default Notification Sound

Source: https://github.com/xan105/node-powertoast/blob/master/TOAST.md

Use this snippet to play the default Windows notification sound when a toast is displayed. Ensure the 'aumid' is correctly set for your application.

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

const toast = new Toast({
  aumid: "com.squirrel.GitHubDesktop.GitHubDesktop",
  title: "Github",
  message: "Someone commented your issue",
  audio: "ms-winsoundevent:Notification.Default"
});

tost.show()
.catch(console.error);
```

--------------------------------

### remove Method

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Removes notification(s) programmatically from the notification center.

```APIDOC
## remove(aumid: string, uniqueID?: string | string[]): Promise<void>

### Description

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 ]`.
```

--------------------------------

### Clear all toast notifications

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Provides a method to remove all toast notifications from the notification center and detach event listeners. This is useful for cleanup.

```javascript
import { Toast } from "node-powertoast";

const toast = new Toast();
try {
  await toast.clear();
} catch (err) {
  // Handle error
}
```

--------------------------------

### Remove specific notifications by AUMID and Unique ID

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Explains how to programmatically remove one or more specific toast notifications from the notification center using their AUMID and optionally their unique IDs. This allows for targeted cleanup.

```javascript
import { remove } from "node-powertoast";

// Remove all notifications for a specific AUMID
try {
  await remove("com.example.app");
} catch (err) {
  // Handle error
}

// Remove a specific notification by AUMID and Unique ID
try {
  await remove("com.example.app", "my-unique-id");
} catch (err) {
  // Handle error
}

// Remove multiple specific notifications by AUMID and an array of Unique IDs
try {
  await remove("com.example.app", ["id1", "id2"]);
} catch (err) {
  // Handle error
}
```

--------------------------------

### Remove notifications using tag and groupLabel

Source: https://github.com/xan105/node-powertoast/blob/master/README.md

Details how to remove notifications when using the `tag` and `groupLabel` properties, by providing the `uniqueID` as an array `[groupLabel, tag]`. This is an advanced usage for precise notification targeting.

```javascript
import { remove } from "node-powertoast";

try {
  await remove("com.example.app", ["my-group-label", "my-tag"]);
} catch (err) {
  // Handle error
}
```
Tokens:
Raw