electron-wns 0.0.0

package/README.md

@@ -0,0 +1,179 @@
+# electron-wns
+
+A TypeScript library for receiving [Windows Push Notification Service (WNS)](https://learn.microsoft.com/en-us/windows/apps/develop/notifications/push-notifications/wns-overview) push messages in the **main process** of an [Electron](https://www.electronjs.org/) application.
+
+---
+
+## How WNS works
+
+```
+┌──────────┐  1. getChannel()   ┌──────────────────────┐
+│ Electron │ ──────────────────▶│   WNS (Microsoft)    │
+│   App    │ ◀────────────────── │                      │
+└──────────┘  channel URI       └──────────────────────┘
+     │
+     │  2. Send URI to backend
+     ▼
+┌──────────┐  3. POST /notify   ┌──────────────────────┐
+│  Your    │ ──────────────────▶│   WNS (Microsoft)    │
+│ Backend  │                    │                      │
+└──────────┘                    └──────────┬───────────┘
+                                           │ 4. push delivered
+                                           ▼
+                                    ┌──────────┐
+                                    │ Electron │  ◀── 'notification' event
+                                    │   App    │
+                                    └──────────┘
+```
+
+1. Your Electron app calls `client.getChannel()` to obtain a **channel URI** from WNS.
+2. Your app sends the channel URI to your backend server.
+3. Whenever your backend needs to push a message, it makes an authenticated HTTP POST to the channel URI via WNS.
+4. WNS delivers the push to the device; `electron-wns` emits a `notification` event in your Electron main process.
+
+---
+
+## Requirements
+
+| Requirement | Details |
+|---|---|
+| **Operating system** | Windows 10 (build 1803) or later |
+| **PowerShell** | `powershell.exe` (Windows PowerShell 5.1+) or `pwsh` (PowerShell 7+) |
+| **Package identity** | The Electron app must be packaged as **MSIX** (or have a sparse-package identity) so that `PushNotificationChannelManager` can register the app with WNS. |
+| **Node.js / Electron** | Node.js ≥ 18, Electron ≥ 22 |
+
+> **Note – unpackaged Electron apps:** The underlying WinRT API (`PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync`) requires a package identity.  
+> For unpackaged Win32 apps, consider using the [Windows App SDK push notification API](https://learn.microsoft.com/en-us/windows/apps/develop/notifications/push-notifications/push-quickstart) or packaging your app with MSIX.
+
+---
+
+## Installation
+
+```bash
+npm install electron-wns
+```
+
+---
+
+## Usage
+
+### Obtain a channel URI
+
+```ts
+import { WNSClient } from 'electron-wns';
+
+const client = new WNSClient();
+
+// Get the WNS channel URI for this app instance.
+// Share this URI with your backend – it uses it to push notifications.
+const channel = await client.getChannel();
+console.log('Channel URI:', channel.uri);
+console.log('Expires at:', channel.expiresAt);
+```
+
+### Listen for incoming push notifications
+
+```ts
+import { WNSClient, WNSNotification } from 'electron-wns';
+
+const client = new WNSClient();
+
+client.on('channelUpdated', (channel) => {
+  console.log('New channel URI:', channel.uri);
+  // Re-register the new URI with your backend
+});
+
+client.on('notification', (n: WNSNotification) => {
+  console.log('Push received!');
+  console.log('  type   :', n.notificationType); // 'toast' | 'tile' | 'badge' | 'raw'
+  console.log('  payload:', n.payload);
+  console.log('  at     :', n.timestamp);
+});
+
+client.on('error', (err) => {
+  console.error('WNS error:', err);
+});
+
+// Start the background WNS listener
+client.startListening();
+
+// Later, when the app is about to quit:
+client.stopListening();
+```
+
+### Refresh an expired channel
+
+```ts
+// Channel URIs have a limited lifetime (check `channel.expiresAt` for the exact expiry).
+// Call refreshChannel() on startup or when the channel is nearing its expiry.
+const newChannel = await client.refreshChannel();
+```
+
+### Custom PowerShell path
+
+```ts
+const client = new WNSClient({ powershellPath: 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe' });
+```
+
+---
+
+## API
+
+### `new WNSClient(options?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `powershellPath` | `string` | `powershell.exe` (Win) / `pwsh` | Path to the PowerShell executable. |
+
+### Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `getChannel()` | `Promise<WNSChannel>` | Obtain (and cache) the WNS channel for this app. |
+| `refreshChannel()` | `Promise<WNSChannel>` | Force a fresh channel request and emit `channelUpdated`. |
+| `startListening()` | `void` | Spawn the background WNS listener. |
+| `stopListening()` | `void` | Kill the background listener. |
+| `isListening()` | `boolean` | Whether the listener is currently running. |
+
+### Events
+
+| Event | Payload | Description |
+|---|---|---|
+| `channelUpdated` | `WNSChannel` | Emitted when a new channel URI is obtained. |
+| `notification` | `WNSNotification` | Emitted for each incoming push notification. |
+| `error` | `Error` | Non-fatal listener error. |
+
+### Types
+
+```ts
+interface WNSChannel {
+  uri: string;       // The channel URI to give to your backend
+  expiresAt: string; // ISO 8601 expiry timestamp – check this field for the exact expiry
+}
+
+interface WNSNotification {
+  notificationType: 'toast' | 'tile' | 'badge' | 'raw';
+  payload: string;   // XML for toast/tile/badge; arbitrary string for raw
+  timestamp: string; // ISO 8601
+}
+```
+
+---
+
+## How it works internally
+
+`electron-wns` ships two PowerShell helper scripts (`scripts/`):
+
+| Script | Purpose |
+|---|---|
+| `get-channel.ps1` | Calls `PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync()` (WinRT) and writes the channel URI as JSON to stdout. |
+| `wns-listener.ps1` | Obtains the channel, subscribes to `PushNotificationChannel.PushNotificationReceived`, and continuously writes incoming notification events as JSON to stdout. |
+
+The TypeScript library spawns these scripts as child processes and communicates via newline-delimited JSON on stdout, keeping the library dependency-free at runtime.
+
+---
+
+## License
+
+MIT
+

package/dist/channel.d.ts

@@ -0,0 +1,11 @@
+/**
+ * WNS channel management – obtaining and caching the push notification channel URI.
+ */
+import { WNSChannel } from './types';
+/**
+ * Request a push notification channel URI from WNS by running the
+ * `get-channel.ps1` PowerShell helper.
+ *
+ * @throws {Error} If PowerShell fails or the channel URI cannot be obtained.
+ */
+export declare function requestChannel(powershellPath: string): Promise<WNSChannel>;

package/dist/channel.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * WNS channel management – obtaining and caching the push notification channel URI.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestChannel = requestChannel;
+const path = __importStar(require("path"));
+const powershell_1 = require("./powershell");
+/** Resolve the path to a bundled PowerShell script. */
+function scriptPath(name) {
+    return path.join(__dirname, '..', 'scripts', name);
+}
+/**
+ * Request a push notification channel URI from WNS by running the
+ * `get-channel.ps1` PowerShell helper.
+ *
+ * @throws {Error} If PowerShell fails or the channel URI cannot be obtained.
+ */
+async function requestChannel(powershellPath) {
+    var _a;
+    const messages = await (0, powershell_1.runPowershell)(powershellPath, scriptPath('get-channel.ps1'));
+    for (const msg of messages) {
+        if (msg.type === 'channel') {
+            const uri = msg.uri;
+            const expiresAt = msg.expiresAt;
+            if (typeof uri !== 'string' || typeof expiresAt !== 'string') {
+                throw new Error('Malformed channel message from PowerShell helper');
+            }
+            return { uri, expiresAt };
+        }
+        if (msg.type === 'error') {
+            throw new Error(String((_a = msg.message) !== null && _a !== void 0 ? _a : 'Unknown error from PowerShell helper'));
+        }
+    }
+    throw new Error('No channel message received from PowerShell helper');
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * electron-wns
+ *
+ * A TypeScript library for receiving Windows Push Notification Service (WNS)
+ * push messages in the main process of an Electron application.
+ *
+ * @example
+ * ```ts
+ * import { WNSClient } from 'electron-wns';
+ *
+ * const client = new WNSClient();
+ *
+ * // Obtain the channel URI and share it with your backend.
+ * const channel = await client.getChannel();
+ * sendToMyServer(channel.uri);
+ *
+ * // Start receiving push notifications.
+ * client.on('notification', (n) => {
+ *   console.log('Received push:', n.notificationType, n.payload);
+ * });
+ * client.startListening();
+ * ```
+ */
+export { WNSClient } from './wns-client';
+export type { WNSChannel, WNSClientOptions, WNSClientEvents, WNSNotification, WNSNotificationType, } from './types';

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * electron-wns
+ *
+ * A TypeScript library for receiving Windows Push Notification Service (WNS)
+ * push messages in the main process of an Electron application.
+ *
+ * @example
+ * ```ts
+ * import { WNSClient } from 'electron-wns';
+ *
+ * const client = new WNSClient();
+ *
+ * // Obtain the channel URI and share it with your backend.
+ * const channel = await client.getChannel();
+ * sendToMyServer(channel.uri);
+ *
+ * // Start receiving push notifications.
+ * client.on('notification', (n) => {
+ *   console.log('Received push:', n.notificationType, n.payload);
+ * });
+ * client.startListening();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WNSClient = void 0;
+var wns_client_1 = require("./wns-client");
+Object.defineProperty(exports, "WNSClient", { enumerable: true, get: function () { return wns_client_1.WNSClient; } });

package/dist/powershell.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Utilities for spawning PowerShell and parsing its newline-delimited JSON output.
+ */
+import { ChildProcess } from 'child_process';
+/** A raw message envelope written by the PowerShell helper. */
+export interface PSMessage {
+    type: 'channel' | 'notification' | 'error';
+    [key: string]: unknown;
+}
+/** Options for {@link spawnPowershell}. */
+export interface SpawnPowershellOptions {
+    /** Path to powershell executable. */
+    powershellPath: string;
+    /** Absolute path to the `.ps1` script to run. */
+    scriptPath: string;
+    /** Called for each complete JSON line written to stdout. */
+    onMessage: (msg: PSMessage) => void;
+    /** Called when the process writes to stderr. */
+    onError: (err: Error) => void;
+    /** Called when the process exits. */
+    onExit: (code: number | null) => void;
+}
+/**
+ * Spawn a PowerShell process running `scriptPath` and parse its newline-delimited
+ * JSON stdout into {@link PSMessage} objects.
+ *
+ * Returns the {@link ChildProcess} so the caller can stop it.
+ */
+export declare function spawnPowershell(opts: SpawnPowershellOptions): ChildProcess;
+/**
+ * Run a PowerShell script, collect all stdout, and resolve with the parsed
+ * array of {@link PSMessage} objects.  Rejects if the process exits non-zero.
+ */
+export declare function runPowershell(powershellPath: string, scriptPath: string): Promise<PSMessage[]>;
+/** Return the default powershell executable name for the current platform. */
+export declare function defaultPowershellPath(): string;

package/dist/powershell.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Utilities for spawning PowerShell and parsing its newline-delimited JSON output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnPowershell = spawnPowershell;
+exports.runPowershell = runPowershell;
+exports.defaultPowershellPath = defaultPowershellPath;
+const child_process_1 = require("child_process");
+/**
+ * Spawn a PowerShell process running `scriptPath` and parse its newline-delimited
+ * JSON stdout into {@link PSMessage} objects.
+ *
+ * Returns the {@link ChildProcess} so the caller can stop it.
+ */
+function spawnPowershell(opts) {
+    const ps = (0, child_process_1.spawn)(opts.powershellPath, [
+        '-NonInteractive',
+        '-NoProfile',
+        '-ExecutionPolicy', 'Bypass',
+        '-File', opts.scriptPath,
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let buffer = '';
+    ps.stdout.setEncoding('utf8');
+    ps.stdout.on('data', (chunk) => {
+        var _a;
+        buffer += chunk;
+        const lines = buffer.split(/\r?\n/);
+        buffer = (_a = lines.pop()) !== null && _a !== void 0 ? _a : '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const msg = JSON.parse(trimmed);
+                opts.onMessage(msg);
+            }
+            catch {
+                // Ignore non-JSON lines (e.g. debug output from PowerShell)
+            }
+        }
+    });
+    ps.stderr.setEncoding('utf8');
+    ps.stderr.on('data', (chunk) => {
+        opts.onError(new Error(chunk.trim()));
+    });
+    ps.on('close', (code) => {
+        opts.onExit(code);
+    });
+    return ps;
+}
+/**
+ * Run a PowerShell script, collect all stdout, and resolve with the parsed
+ * array of {@link PSMessage} objects.  Rejects if the process exits non-zero.
+ */
+function runPowershell(powershellPath, scriptPath) {
+    return new Promise((resolve, reject) => {
+        const messages = [];
+        const proc = spawnPowershell({
+            powershellPath,
+            scriptPath,
+            onMessage: (msg) => messages.push(msg),
+            onError: (err) => {
+                // Collect stderr but don't reject yet – wait for exit code
+                messages.push({ type: 'error', message: err.message });
+            },
+            onExit: (code) => {
+                if (code !== 0) {
+                    const errMsg = messages
+                        .filter((m) => m.type === 'error')
+                        .map((m) => String(m.message))
+                        .join(' ');
+                    reject(new Error(`PowerShell exited with code ${code}: ${errMsg}`));
+                }
+                else {
+                    resolve(messages);
+                }
+            },
+        });
+        // Keep a reference so the GC doesn't collect the process
+        void proc;
+    });
+}
+/** Return the default powershell executable name for the current platform. */
+function defaultPowershellPath() {
+    return process.platform === 'win32' ? 'powershell.exe' : 'pwsh';
+}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Type definitions for electron-wns
+ */
+/** The type of a WNS notification payload. */
+export type WNSNotificationType = 'toast' | 'tile' | 'badge' | 'raw';
+/** A notification received from WNS. */
+export interface WNSNotification {
+    /** The notification type as reported by WNS. */
+    notificationType: WNSNotificationType;
+    /** The raw string payload of the notification (XML for toast/tile/badge, any string for raw). */
+    payload: string;
+    /** ISO 8601 timestamp of when the notification was received. */
+    timestamp: string;
+}
+/** A WNS push notification channel. */
+export interface WNSChannel {
+    /** The channel URI to send to your backend server. */
+    uri: string;
+    /** ISO 8601 expiry time – request a new channel URI after this point. */
+    expiresAt: string;
+}
+/** Options for creating a {@link WNSClient}. */
+export interface WNSClientOptions {
+    /**
+     * Override the path to `powershell.exe` (or `pwsh`).
+     * Defaults to `powershell.exe` on Windows, `pwsh` elsewhere.
+     */
+    powershellPath?: string;
+}
+/** Events emitted by {@link WNSClient}. */
+export interface WNSClientEvents {
+    /** Fired when a new channel URI is obtained from WNS. */
+    channelUpdated: [channel: WNSChannel];
+    /** Fired each time a push notification arrives. */
+    notification: [notification: WNSNotification];
+    /** Fired when a recoverable error occurs in the background listener. */
+    error: [error: Error];
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Type definitions for electron-wns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/wns-client.d.ts

@@ -0,0 +1,63 @@
+/**
+ * WNSClient – the main entry point for receiving WNS push notifications in an
+ * Electron main process.
+ *
+ * Usage:
+ * ```ts
+ * import { WNSClient } from 'electron-wns';
+ *
+ * const client = new WNSClient();
+ *
+ * const channel = await client.getChannel();
+ * console.log('Send this URI to your backend:', channel.uri);
+ *
+ * client.on('notification', (n) => console.log('Push received:', n.payload));
+ * client.startListening();
+ * ```
+ */
+import { EventEmitter } from 'events';
+import { WNSChannel, WNSClientOptions } from './types';
+export declare class WNSClient extends EventEmitter {
+    private readonly powershellPath;
+    private cachedChannel;
+    private listenerProcess;
+    constructor(options?: WNSClientOptions);
+    /**
+     * Obtain a WNS push notification channel for this application.
+     *
+     * The result is cached in memory; call `refreshChannel()` to force a
+     * fresh request (e.g. after the channel expiry date has passed).
+     *
+     * @throws {Error} On Windows if the app does not have a package identity
+     *   (MSIX packaging is required for `PushNotificationChannelManager`).
+     */
+    getChannel(): Promise<WNSChannel>;
+    /**
+     * Force a new channel request and update the internal cache.
+     * Emits `channelUpdated` with the new channel.
+     */
+    refreshChannel(): Promise<WNSChannel>;
+    /**
+     * Start listening for incoming push notifications.
+     *
+     * Spawns a PowerShell background process (`wns-listener.ps1`) that
+     * registers for `PushNotificationReceived` events on the WNS channel and
+     * pipes them back as newline-delimited JSON.
+     *
+     * Emits:
+     * - `channelUpdated` once the channel has been registered
+     * - `notification` for each incoming push
+     * - `error` for non-fatal errors (the listener continues running)
+     *
+     * Calling `startListening()` while already listening is a no-op.
+     */
+    startListening(): void;
+    /**
+     * Stop the background listener.  Safe to call even if not currently
+     * listening.
+     */
+    stopListening(): void;
+    /** Returns `true` if the background listener is currently running. */
+    isListening(): boolean;
+    private handleListenerMessage;
+}

package/dist/wns-client.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * WNSClient – the main entry point for receiving WNS push notifications in an
+ * Electron main process.
+ *
+ * Usage:
+ * ```ts
+ * import { WNSClient } from 'electron-wns';
+ *
+ * const client = new WNSClient();
+ *
+ * const channel = await client.getChannel();
+ * console.log('Send this URI to your backend:', channel.uri);
+ *
+ * client.on('notification', (n) => console.log('Push received:', n.payload));
+ * client.startListening();
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WNSClient = void 0;
+const events_1 = require("events");
+const path = __importStar(require("path"));
+const powershell_1 = require("./powershell");
+const channel_1 = require("./channel");
+class WNSClient extends events_1.EventEmitter {
+    constructor(options = {}) {
+        var _a;
+        super();
+        this.cachedChannel = null;
+        this.listenerProcess = null;
+        this.powershellPath = (_a = options.powershellPath) !== null && _a !== void 0 ? _a : (0, powershell_1.defaultPowershellPath)();
+    }
+    // ── Channel ────────────────────────────────────────────────────────────────
+    /**
+     * Obtain a WNS push notification channel for this application.
+     *
+     * The result is cached in memory; call `refreshChannel()` to force a
+     * fresh request (e.g. after the channel expiry date has passed).
+     *
+     * @throws {Error} On Windows if the app does not have a package identity
+     *   (MSIX packaging is required for `PushNotificationChannelManager`).
+     */
+    async getChannel() {
+        if (!this.cachedChannel) {
+            this.cachedChannel = await (0, channel_1.requestChannel)(this.powershellPath);
+        }
+        return this.cachedChannel;
+    }
+    /**
+     * Force a new channel request and update the internal cache.
+     * Emits `channelUpdated` with the new channel.
+     */
+    async refreshChannel() {
+        this.cachedChannel = await (0, channel_1.requestChannel)(this.powershellPath);
+        this.emit('channelUpdated', this.cachedChannel);
+        return this.cachedChannel;
+    }
+    // ── Listening ──────────────────────────────────────────────────────────────
+    /**
+     * Start listening for incoming push notifications.
+     *
+     * Spawns a PowerShell background process (`wns-listener.ps1`) that
+     * registers for `PushNotificationReceived` events on the WNS channel and
+     * pipes them back as newline-delimited JSON.
+     *
+     * Emits:
+     * - `channelUpdated` once the channel has been registered
+     * - `notification` for each incoming push
+     * - `error` for non-fatal errors (the listener continues running)
+     *
+     * Calling `startListening()` while already listening is a no-op.
+     */
+    startListening() {
+        if (this.listenerProcess)
+            return;
+        const scriptFile = path.join(__dirname, '..', 'scripts', 'wns-listener.ps1');
+        this.listenerProcess = (0, powershell_1.spawnPowershell)({
+            powershellPath: this.powershellPath,
+            scriptPath: scriptFile,
+            onMessage: (msg) => this.handleListenerMessage(msg),
+            onError: (err) => this.emit('error', err),
+            onExit: (code) => {
+                this.listenerProcess = null;
+                if (code !== 0 && code !== null) {
+                    this.emit('error', new Error(`WNS listener exited with code ${code}`));
+                }
+            },
+        });
+    }
+    /**
+     * Stop the background listener.  Safe to call even if not currently
+     * listening.
+     */
+    stopListening() {
+        if (this.listenerProcess) {
+            this.listenerProcess.kill();
+            this.listenerProcess = null;
+        }
+    }
+    /** Returns `true` if the background listener is currently running. */
+    isListening() {
+        return this.listenerProcess !== null;
+    }
+    // ── Internal ───────────────────────────────────────────────────────────────
+    handleListenerMessage(msg) {
+        var _a, _b, _c, _d, _e, _f;
+        switch (msg.type) {
+            case 'channel': {
+                const uri = String((_a = msg.uri) !== null && _a !== void 0 ? _a : '');
+                const expiresAt = String((_b = msg.expiresAt) !== null && _b !== void 0 ? _b : '');
+                if (uri) {
+                    const channel = { uri, expiresAt };
+                    this.cachedChannel = channel;
+                    this.emit('channelUpdated', channel);
+                }
+                break;
+            }
+            case 'notification': {
+                const notification = {
+                    notificationType: (_c = msg.notificationType) !== null && _c !== void 0 ? _c : 'raw',
+                    payload: String((_d = msg.payload) !== null && _d !== void 0 ? _d : ''),
+                    timestamp: String((_e = msg.timestamp) !== null && _e !== void 0 ? _e : new Date().toISOString()),
+                };
+                this.emit('notification', notification);
+                break;
+            }
+            case 'error': {
+                this.emit('error', new Error(String((_f = msg.message) !== null && _f !== void 0 ? _f : 'Unknown listener error')));
+                break;
+            }
+        }
+    }
+}
+exports.WNSClient = WNSClient;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "electron-wns",
+  "version": "0.0.0",
+  "description": "Library for receiving Windows Push Notification Service (WNS) push messages in Electron apps",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepare": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iotum/electron-wns.git"
+  },
+  "keywords": [
+    "electron",
+    "wns",
+    "push",
+    "notifications",
+    "windows"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/iotum/electron-wns/issues"
+  },
+  "homepage": "https://github.com/iotum/electron-wns#readme",
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.37",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/get-channel.ps1

@@ -0,0 +1,73 @@
+# get-channel.ps1
+#
+# Obtains a WNS push notification channel URI for the current application and
+# writes a single JSON object to stdout:
+#
+#   { "type": "channel", "uri": "<channel-uri>", "expiresAt": "<ISO-8601>" }
+#
+# On failure writes:
+#   { "type": "error", "message": "<description>" }
+# and exits with code 1.
+#
+# Requirements:
+#   - Windows 10 / Windows Server 2019 or later
+#   - The calling application must have a package identity (MSIX-packaged).
+
+[CmdletBinding()]
+param()
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# ---------------------------------------------------------------------------
+# Helper: convert a WinRT IAsyncOperation<T> to a .NET Task<T> and wait on it
+# ---------------------------------------------------------------------------
+function Await-WinRTAsync {
+    param(
+        [Parameter(Mandatory)] $AsyncOperation,
+        [Parameter(Mandatory)] [Type] $ResultType
+    )
+
+    Add-Type -AssemblyName System.Runtime.WindowsRuntime | Out-Null
+
+    $extensionMethod = [System.WindowsRuntimeSystemExtensions].GetMethods() |
+        Where-Object {
+            $_.Name -eq 'AsTask' -and
+            $_.GetParameters().Count -eq 1 -and
+            $_.IsGenericMethod
+        } |
+        Select-Object -First 1
+
+    $task = $extensionMethod.MakeGenericMethod($ResultType).Invoke($null, @($AsyncOperation))
+    $task.Wait() | Out-Null
+    return $task.Result
+}
+
+try {
+    Add-Type -AssemblyName System.Runtime.WindowsRuntime | Out-Null
+
+    # Load WinRT push-notification types
+    $channelManagerType = [Windows.Networking.PushNotifications.PushNotificationChannelManager,
+        Windows.Networking.PushNotifications, ContentType=WindowsRuntime]
+    $channelType = [Windows.Networking.PushNotifications.PushNotificationChannel,
+        Windows.Networking.PushNotifications, ContentType=WindowsRuntime]
+
+    # Request a channel (async → sync)
+    $asyncOp   = $channelManagerType::CreatePushNotificationChannelForApplicationAsync()
+    $channel   = Await-WinRTAsync -AsyncOperation $asyncOp -ResultType $channelType
+
+    $result = [PSCustomObject]@{
+        type      = 'channel'
+        uri       = $channel.Uri
+        expiresAt = $channel.ExpirationTime.ToUniversalTime().ToString('o')
+    }
+    Write-Output (ConvertTo-Json $result -Compress)
+}
+catch {
+    $err = [PSCustomObject]@{
+        type    = 'error'
+        message = $_.Exception.Message
+    }
+    Write-Output (ConvertTo-Json $err -Compress)
+    exit 1
+}

package/scripts/wns-listener.ps1

@@ -0,0 +1,136 @@
+# wns-listener.ps1
+#
+# Registers a WNS push notification channel for the current application,
+# emits the channel details, and then waits for push notifications.
+#
+# Every event is written to stdout as a compact JSON object followed by a
+# newline so that the Node.js parent process can parse it incrementally.
+#
+# Message types:
+#   { "type": "channel",      "uri": "...", "expiresAt": "..." }
+#   { "type": "notification", "notificationType": "...", "payload": "...", "timestamp": "..." }
+#   { "type": "error",        "message": "..." }
+#
+# The script runs until the parent process terminates it (SIGTERM / kill).
+#
+# Requirements:
+#   - Windows 10 / Windows Server 2019 or later
+#   - The calling application must have a package identity (MSIX-packaged).
+
+[CmdletBinding()]
+param()
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# ---------------------------------------------------------------------------
+# Helper: convert a WinRT IAsyncOperation<T> to a .NET Task<T> and wait
+# ---------------------------------------------------------------------------
+function Await-WinRTAsync {
+    param(
+        [Parameter(Mandatory)] $AsyncOperation,
+        [Parameter(Mandatory)] [Type] $ResultType
+    )
+    Add-Type -AssemblyName System.Runtime.WindowsRuntime | Out-Null
+    $extensionMethod = [System.WindowsRuntimeSystemExtensions].GetMethods() |
+        Where-Object {
+            $_.Name -eq 'AsTask' -and
+            $_.GetParameters().Count -eq 1 -and
+            $_.IsGenericMethod
+        } |
+        Select-Object -First 1
+    $task = $extensionMethod.MakeGenericMethod($ResultType).Invoke($null, @($AsyncOperation))
+    $task.Wait() | Out-Null
+    return $task.Result
+}
+
+# ---------------------------------------------------------------------------
+# Write a JSON message to stdout (single line)
+# ---------------------------------------------------------------------------
+function Write-JsonMessage {
+    param([hashtable] $Data)
+    [Console]::Out.WriteLine((ConvertTo-Json ([PSCustomObject]$Data) -Compress -Depth 5))
+    [Console]::Out.Flush()
+}
+
+try {
+    Add-Type -AssemblyName System.Runtime.WindowsRuntime | Out-Null
+
+    $channelManagerType = [Windows.Networking.PushNotifications.PushNotificationChannelManager,
+        Windows.Networking.PushNotifications, ContentType=WindowsRuntime]
+    $channelType = [Windows.Networking.PushNotifications.PushNotificationChannel,
+        Windows.Networking.PushNotifications, ContentType=WindowsRuntime]
+
+    # Obtain the channel
+    $asyncOp = $channelManagerType::CreatePushNotificationChannelForApplicationAsync()
+    $channel = Await-WinRTAsync -AsyncOperation $asyncOp -ResultType $channelType
+
+    # Report the channel URI to the Node.js process
+    Write-JsonMessage @{
+        type      = 'channel'
+        uri       = $channel.Uri
+        expiresAt = $channel.ExpirationTime.ToUniversalTime().ToString('o')
+    }
+
+    # ---------------------------------------------------------------------------
+    # Subscribe to incoming push notifications
+    # ---------------------------------------------------------------------------
+    # A thread-safe queue shared between the WinRT event callback and the
+    # polling loop below.
+    $queue = [System.Collections.Concurrent.ConcurrentQueue[hashtable]]::new()
+
+    $handlerBlock = {
+        param($sender, $eventArgs)
+        $n = $eventArgs.Notification
+        $notifType = $n.NotificationType.ToString().ToLower()
+        $payload = ''
+        if ($notifType -eq 'raw') {
+            $payload = $n.RawNotification.Content
+        }
+        elseif ($notifType -eq 'toast') {
+            $payload = $n.ToastNotification.Content.GetXml()
+        }
+        elseif ($notifType -eq 'tile') {
+            $payload = $n.TileNotification.Content.GetXml()
+        }
+        elseif ($notifType -eq 'badge') {
+            $payload = $n.BadgeNotification.Content.GetXml()
+        }
+
+        # Mark the notification as handled so Windows does not show a system UI
+        $eventArgs.Cancel = $true
+
+        $queue.Enqueue(@{
+            type             = 'notification'
+            notificationType = $notifType
+            payload          = $payload
+            timestamp        = [DateTime]::UtcNow.ToString('o')
+        })
+    }
+
+    $receivedType = [Windows.Foundation.TypedEventHandler``2].MakeGenericType(
+        $channelType,
+        [Windows.Networking.PushNotifications.PushNotificationReceivedEventArgs,
+            Windows.Networking.PushNotifications, ContentType=WindowsRuntime]
+    )
+    $delegate = [Delegate]::CreateDelegate($receivedType, $handlerBlock.GetNewClosure(), 'Invoke')
+    $channel.add_PushNotificationReceived($delegate)
+
+    # ---------------------------------------------------------------------------
+    # Poll the queue until the process is terminated
+    # ---------------------------------------------------------------------------
+    while ($true) {
+        $item = $null
+        while ($queue.TryDequeue([ref] $item)) {
+            Write-JsonMessage $item
+        }
+        Start-Sleep -Milliseconds 200
+    }
+}
+catch {
+    Write-JsonMessage @{
+        type    = 'error'
+        message = $_.Exception.Message
+    }
+    exit 1
+}