electron-wns 0.0.0 → 0.0.4

package/README.md

@@ -1,179 +1,99 @@
-# 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
-
+# electron-wns
+
+Node native addon that allows you to receive push messages from Windows Push Notifications Services (WNS), in Electron (and node).
+
+- Currently in an initial state of development, but so far I have been able to successfully
+use this library to obtain a channel URI (with an included token), that could be used to send WNS
+push messages to.
+
+- Tested with Electron 32.2.4, but probably will work with most modern versions of electron (and node)
+- Tested by launching in a packaged, and code signed context via a .MSIX installer (see https://www.electronforge.io/config/makers/msix)
+
+- Library is actively being improved!
+
+## USAGE
+
+1. Clone this repo
+2. npm install
+3. npm run build (change the Electron version in package.json to match the version of electron your working with)
+4. Copy the built electron_wns.node into your electron project.
+5. Ensure that it is packaged up with the app. For electron packager / forge, you may need to adjust packager config:
+
+Example:
+- Place the .node file in assets/win32/wns/electron_wns.node within your repo.
+- Adjust packager config to ensure that folder is packaged up with the application files:
+```
+  packagerConfig: {
+    extraResource: [
+      `./assets/${process.platform}`
+    ]
+  }
+```
+- To reference the .node file by its absolute path I recommend a helper function
+that works both when the app is packaged or not:
+
+src/Assets.ts
+```
+import { app } from 'electron';
+import path from 'path';
+
+// Helper functions for accessing assets/ folder when packaged with running electron app.
+class Assets {
+  static getURL() {
+    if (app.isPackaged) {
+      return process.resourcesPath;
+    } else {
+      return path.normalize(`${__dirname}../../../assets`);
+    }
+  }
+}
+
+export default Assets;
+```
+
+- require() the .node file to use it in the javascripts of your main process like so:
+```
+  const assetsURL = Assets.getURL();
+  const addonPath = path.join(assetsURL, 'win32', 'wns', 'electron_wns.node');
+
+  const runtimeRequire = typeof __non_webpack_require__ === 'function' ? __non_webpack_require__ : require;
+
+  // Note: its a good idea to try/catch the following require() statement which will throw a MODULE_NOT_FOUND
+  // if the absolute path the .node file is wrong, or is compiled/built againts the wrong electron/node ABI.
+  electronWNS = runtimeRequire(addonPath); 
+
+  const channel = await electronWNS.getChannel();
+  console.log('WNS channel URI:', channel.uri); // Your backend can use this to send to this device
+
+  electronWNS.startForegroundNotifications((notification) => {
+    console.log('Foreground WNS notification:', notification);
+  });
+
+  electronWNS.stopForegroundNotifications();
+```
+
+## Exposed API of electron_wns.node:
+
+- `getChannel(): Promise<{ uri: string; expirationTicks: number }>`
+- `startForegroundNotifications(callback: (notification) => void): void`
+- `stopForegroundNotifications(): void`
+
+## Structure of Received Notifications
+
+```js
+{
+  type: 'raw' | 'toast' | 'tile' | 'badge' | 'unknown',
+  content: string,
+  headers: Record<string, string> // populated for raw notifications
+}
+```
+
+## TO COME:
+- Typescript types
+- Improving the way the library is integrated into your app - so that you can npm install, and access via a javascript wrapper
+- electron rebuild support that automatically would detect your version of electron (electron rebuild)
+- Typescript types/etc.
+
+## An Alternative Library:
+- There is the NodeRT project: https://github.com/NodeRT/NodeRT
+- But that is currently very outdated and does not compile against more modern versions of node/electron

package/binding.gyp

@@ -0,0 +1,34 @@
+{
+  "targets": [
+    {
+      "target_name": "electron_wns",
+      "sources": [
+        "src/electron_wns.cpp"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "defines": [
+        "NAPI_CPP_EXCEPTIONS"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "conditions": [
+        ["OS=='win'", {
+          "libraries": [
+            "runtimeobject.lib",
+            "windowsapp.lib"
+          ],
+          "msvs_settings": {
+            "VCCLCompilerTool": {
+              "AdditionalOptions": [
+                "/EHsc"
+              ]
+            }
+          }
+        }]
+      ]
+    }
+  ]
+}

package/index.js

@@ -0,0 +1,11 @@
+const path = require('path');
+
+const addonPath = path.join(__dirname, 'build', 'Release', 'electron_wns.node');
+const binding = require(addonPath);
+
+console.log('==> index.js binding.getChannel: ', typeof binding.getChannel);
+module.exports = {
+  getChannel: binding.getChannel,
+  startForegroundNotifications: binding.startForegroundNotifications,
+  stopForegroundNotifications: binding.stopForegroundNotifications,
+};

package/package.json

@@ -1,40 +1,29 @@
-{
-  "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"
-  }
-}
+{
+  "name": "electron-wns",
+  "version": "0.0.4",
+  "description": "Native Node addon for WNS channel creation and foreground notification listening",
+  "main": "index.js",
+  "scripts": {
+    "install": "npm run build:electron32",
+    "build": "npm run build:electron32",
+    "build:electron32": "electron-rebuild -f -v 32.2.4 -w electron-wns --module-dir .",
+    "build:node": "node-gyp rebuild",
+    "clean": "node-gyp clean"
+  },
+  "keywords": [
+    "electron",
+    "wns",
+    "windows",
+    "native-addon"
+  ],
+  "license": "MIT",
+  "gypfile": true,
+  "dependencies": {
+    "bindings": "^1.5.0",
+    "node-addon-api": "^8.1.0"
+  },
+  "devDependencies": {
+    "@electron/rebuild": "^3.7.1",
+    "node-gyp": "^11.1.0"
+  }
+}

package/src/electron_wns.cpp

@@ -0,0 +1,256 @@
+#include <napi.h>
+
+#include <mutex>
+#include <string>
+#include <unordered_map>
+
+#include <Windows.h>
+
+#include <winrt/Windows.Data.Xml.Dom.h>
+#include <winrt/Windows.Foundation.h>
+#include <winrt/Windows.Foundation.Collections.h>
+#include <winrt/Windows.Networking.PushNotifications.h>
+#include <winrt/Windows.UI.Notifications.h>
+
+namespace {
+using winrt::Windows::Networking::PushNotifications::PushNotificationChannel;
+using winrt::Windows::Networking::PushNotifications::PushNotificationChannelManager;
+using winrt::Windows::Networking::PushNotifications::PushNotificationReceivedEventArgs;
+using winrt::Windows::Networking::PushNotifications::PushNotificationType;
+
+std::mutex g_mutex;
+std::once_flag g_apartmentInitFlag;
+PushNotificationChannel g_channel{nullptr};
+winrt::event_token g_notificationToken{};
+bool g_isListening = false;
+Napi::ThreadSafeFunction g_notificationTsfn;
+
+std::string ToUtf8(std::wstring const& input);
+std::string ToUtf8(winrt::hstring const& input);
+PushNotificationChannel GetOrCreateChannel();
+
+class GetChannelWorker : public Napi::AsyncWorker {
+ public:
+  GetChannelWorker(const Napi::Env& env, Napi::Promise::Deferred deferred)
+      : Napi::AsyncWorker(env), deferred_(deferred) {}
+
+  ~GetChannelWorker() override = default;
+
+  void Execute() override {
+    try {
+      auto channel = GetOrCreateChannel();
+      uri_ = ToUtf8(channel.Uri());
+
+      const auto expiration = channel.ExpirationTime();
+      expirationTicks_ = expiration.time_since_epoch().count();
+    } catch (const winrt::hresult_error& error) {
+      SetError(ToUtf8(error.message()));
+    } catch (const std::exception& error) {
+      SetError(error.what());
+    }
+  }
+
+  void OnOK() override {
+    Napi::Object result = Napi::Object::New(Env());
+    result.Set("uri", uri_);
+    result.Set("expirationTicks", Napi::Number::New(Env(), static_cast<double>(expirationTicks_)));
+    deferred_.Resolve(result);
+  }
+
+  void OnError(const Napi::Error& error) override { deferred_.Reject(error.Value()); }
+
+ private:
+  Napi::Promise::Deferred deferred_;
+  std::string uri_;
+  int64_t expirationTicks_ = 0;
+};
+
+void EnsureApartmentInitialized() {
+  std::call_once(g_apartmentInitFlag, []() {
+    try {
+      winrt::init_apartment(winrt::apartment_type::multi_threaded);
+    } catch (const winrt::hresult_error& error) {
+      if (error.code() != RPC_E_CHANGED_MODE) {
+        throw;
+      }
+    }
+  });
+}
+
+std::string ToUtf8(std::wstring const& input) {
+  if (input.empty()) {
+    return {};
+  }
+
+  int required = WideCharToMultiByte(CP_UTF8, 0, input.c_str(), static_cast<int>(input.size()), nullptr, 0, nullptr, nullptr);
+  std::string output(static_cast<size_t>(required), '\0');
+  WideCharToMultiByte(CP_UTF8, 0, input.c_str(), static_cast<int>(input.size()), output.data(), required, nullptr, nullptr);
+  return output;
+}
+
+std::string ToUtf8(winrt::hstring const& input) {
+  return ToUtf8(std::wstring(input));
+}
+
+PushNotificationChannel GetOrCreateChannel() {
+  EnsureApartmentInitialized();
+
+  std::lock_guard<std::mutex> lock(g_mutex);
+  if (g_channel) {
+    return g_channel;
+  }
+
+  auto asyncOp = PushNotificationChannelManager::CreatePushNotificationChannelForApplicationAsync();
+  g_channel = asyncOp.get();
+  return g_channel;
+}
+
+std::string NotificationTypeToString(PushNotificationType type) {
+  switch (type) {
+    case PushNotificationType::Toast:
+      return "toast";
+    case PushNotificationType::Tile:
+      return "tile";
+    case PushNotificationType::Badge:
+      return "badge";
+    case PushNotificationType::Raw:
+      return "raw";
+    default:
+      return "unknown";
+  }
+}
+
+Napi::Value GetChannelWrapped(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  auto deferred = Napi::Promise::Deferred::New(env);
+
+  auto* worker = new GetChannelWorker(env, deferred);
+  worker->Queue();
+
+  return deferred.Promise();
+}
+
+Napi::Value StartForegroundNotificationsWrapped(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsFunction()) {
+    throw Napi::TypeError::New(env, "startForegroundNotifications requires a callback function");
+  }
+
+  Napi::Function callback = info[0].As<Napi::Function>();
+
+  EnsureApartmentInitialized();
+  auto channel = GetOrCreateChannel();
+
+  std::lock_guard<std::mutex> lock(g_mutex);
+
+  if (g_isListening) {
+    if (g_notificationTsfn) {
+      g_notificationTsfn.Release();
+    }
+    channel.PushNotificationReceived(g_notificationToken);
+    g_isListening = false;
+  }
+
+  g_notificationTsfn = Napi::ThreadSafeFunction::New(
+      env,
+      callback,
+      "wns-foreground-notification-callback",
+      0,
+      1);
+
+  g_notificationToken = channel.PushNotificationReceived([](PushNotificationChannel const&, PushNotificationReceivedEventArgs const& args) {
+    std::lock_guard<std::mutex> callbackLock(g_mutex);
+    if (!g_notificationTsfn) {
+      return;
+    }
+
+    struct NotificationPayload {
+      std::string type;
+      std::string content;
+      std::unordered_map<std::string, std::string> headers;
+    } payload;
+
+    payload.type = NotificationTypeToString(args.NotificationType());
+
+    if (args.NotificationType() == PushNotificationType::Raw) {
+      auto raw = args.RawNotification();
+      payload.content = ToUtf8(raw.Content());
+
+      auto headerMap = raw.Headers();
+      for (const auto& pair : headerMap) {
+        payload.headers[ToUtf8(pair.Key())] = ToUtf8(pair.Value());
+      }
+    } else if (args.ToastNotification()) {
+      auto xmlDocument = args.ToastNotification().Content();
+      payload.content = ToUtf8(xmlDocument.GetXml());
+    }
+
+    auto status = g_notificationTsfn.BlockingCall(
+        new NotificationPayload(std::move(payload)),
+        [](Napi::Env callbackEnv, Napi::Function jsCallback, NotificationPayload* data) {
+          Napi::Object notification = Napi::Object::New(callbackEnv);
+          notification.Set("type", data->type);
+          notification.Set("content", data->content);
+
+          Napi::Object headers = Napi::Object::New(callbackEnv);
+          for (const auto& [key, value] : data->headers) {
+            headers.Set(key, value);
+          }
+          notification.Set("headers", headers);
+
+          jsCallback.Call({notification});
+          delete data;
+        });
+
+    if (status != napi_ok) {
+      return;
+    }
+  });
+
+  g_isListening = true;
+  return env.Undefined();
+}
+
+Napi::Value StopForegroundNotificationsWrapped(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  EnsureApartmentInitialized();
+
+  std::lock_guard<std::mutex> lock(g_mutex);
+
+  if (!g_isListening) {
+    return env.Undefined();
+  }
+
+  if (g_channel) {
+    g_channel.PushNotificationReceived(g_notificationToken);
+  }
+
+  if (g_notificationTsfn) {
+    g_notificationTsfn.Release();
+    g_notificationTsfn = {};
+  }
+
+  g_isListening = false;
+  return env.Undefined();
+}
+
+Napi::Object Initialize(Napi::Env env, Napi::Object exports) {
+  try {
+    EnsureApartmentInitialized();
+  } catch (const winrt::hresult_error& error) {
+    Napi::Error::New(env, ToUtf8(error.message())).ThrowAsJavaScriptException();
+    return exports;
+  } catch (const std::exception& error) {
+    Napi::Error::New(env, error.what()).ThrowAsJavaScriptException();
+    return exports;
+  }
+
+  exports.Set("getChannel", Napi::Function::New(env, GetChannelWrapped));
+  exports.Set("startForegroundNotifications", Napi::Function::New(env, StartForegroundNotificationsWrapped));
+  exports.Set("stopForegroundNotifications", Napi::Function::New(env, StopForegroundNotificationsWrapped));
+
+  return exports;
+}
+}  // namespace
+
+NODE_API_MODULE(electron_wns, Initialize)

package/dist/channel.d.ts

@@ -1,11 +0,0 @@
-/**
- * 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>;