@mcesystems/usb-device-listener 1.0.15 → 1.0.17

package/binding.gyp

@@ -0,0 +1,41 @@
+{
+	"targets": [
+		{
+			"target_name": "usb_device_listener",
+			"sources": [
+				"native/addon.cc",
+				"native/usb_listener.cc"
+			],
+			"include_dirs": [
+				"<!@(node -p \"require('node-addon-api').include\")"
+			],
+			"dependencies": [
+				"<!(node -p \"require('node-addon-api').gyp\")"
+			],
+			"defines": [
+				"NAPI_DISABLE_CPP_EXCEPTIONS",
+				"UNICODE",
+				"_UNICODE"
+			],
+			"conditions": [
+				[
+					"OS=='win'",
+					{
+						"libraries": [
+							"Setupapi.lib",
+							"Cfgmgr32.lib"
+						],
+						"msvs_settings": {
+							"VCCLCompilerTool": {
+								"ExceptionHandling": 1,
+								"AdditionalOptions": [
+									"/std:c++20"
+								]
+							}
+						}
+					}
+				]
+			]
+		}
+	]
+}

package/dist/index.cjs

@@ -0,0 +1,155 @@
+const __importMetaUrl = require("url").pathToFileURL(__filename).href;
+if (typeof import.meta === "undefined") {
+	Object.defineProperty(globalThis, "import", { value: { meta: { url: __importMetaUrl } } });
+}
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => UsbDeviceListener
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_module = require("node:module");
+var import_node_path = __toESM(require("node:path"), 1);
+var import_node_url = require("node:url");
+
+// src/device-filter.ts
+function toHexString(value) {
+  return value.toString(16).toUpperCase().padStart(4, "0");
+}
+function matchesDevice(device, target) {
+  const deviceVid = toHexString(device.vid);
+  const devicePid = toHexString(device.pid);
+  const targetVid = target.vid.toUpperCase();
+  const targetPid = target.pid.toUpperCase();
+  return deviceVid === targetVid && devicePid === targetPid;
+}
+function matchesAnyDevice(device, targets) {
+  return targets.some((target) => matchesDevice(device, target));
+}
+function shouldNotifyDevice(device, config) {
+  if (config.ignoredDevices && config.ignoredDevices.length > 0) {
+    if (matchesAnyDevice(device, config.ignoredDevices)) {
+      return false;
+    }
+  }
+  if (config.listenOnlyDevices && config.listenOnlyDevices.length > 0) {
+    if (!matchesAnyDevice(device, config.listenOnlyDevices)) {
+      return false;
+    }
+  }
+  if (config.targetDevices && config.targetDevices.length > 0) {
+    if (!matchesAnyDevice(device, config.targetDevices)) {
+      return false;
+    }
+  }
+  if (config.logicalPortMap && Object.keys(config.logicalPortMap).length > 0) {
+    if (!(device.locationInfo in config.logicalPortMap)) {
+      return false;
+    }
+  }
+  return true;
+}
+function applyLogicalPortMapping(device, config) {
+  if (config.logicalPortMap && device.locationInfo in config.logicalPortMap) {
+    return {
+      ...device,
+      logicalPort: config.logicalPortMap[device.locationInfo]
+    };
+  }
+  return device;
+}
+
+// src/index.ts
+var __filename = (0, import_node_url.fileURLToPath)(__importMetaUrl);
+var __dirname = import_node_path.default.dirname(__filename);
+var require2 = (0, import_node_module.createRequire)(__importMetaUrl);
+var packageRoot = import_node_path.default.join(__dirname, "..");
+var addon = require2("node-gyp-build")(packageRoot);
+var { listDevices, onDeviceAdd, onDeviceRemove, startListening, stopListening } = addon;
+var UsbDeviceListener = class {
+  config = {};
+  userAddCallback = null;
+  userRemoveCallback = null;
+  /**
+   * Start listening for USB device events
+   */
+  startListening(config) {
+    if (typeof config !== "object" || config === null) {
+      throw new TypeError("Config must be an object");
+    }
+    this.config = config;
+    startListening();
+  }
+  /**
+   * Stop listening for USB device events
+   */
+  stopListening() {
+    stopListening();
+  }
+  /**
+   * Register callback for device connection events
+   */
+  onDeviceAdd(callback) {
+    if (typeof callback !== "function") {
+      throw new TypeError("Callback must be a function");
+    }
+    this.userAddCallback = callback;
+    onDeviceAdd((device) => {
+      if (shouldNotifyDevice(device, this.config)) {
+        const enrichedDevice = applyLogicalPortMapping(device, this.config);
+        this.userAddCallback?.(enrichedDevice);
+      }
+    });
+  }
+  /**
+   * Register callback for device disconnection events
+   */
+  onDeviceRemove(callback) {
+    if (typeof callback !== "function") {
+      throw new TypeError("Callback must be a function");
+    }
+    this.userRemoveCallback = callback;
+    onDeviceRemove((device) => {
+      if (shouldNotifyDevice(device, this.config)) {
+        const enrichedDevice = applyLogicalPortMapping(device, this.config);
+        this.userRemoveCallback?.(enrichedDevice);
+      }
+    });
+  }
+  /**
+   * List all currently connected USB devices
+   */
+  listDevices() {
+    return listDevices();
+  }
+};
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts", "../src/device-filter.ts"],
+  "sourcesContent": ["import { createRequire } from \"node:module\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { applyLogicalPortMapping, shouldNotifyDevice } from \"./device-filter\";\nimport type {\n\tDeviceAddCallback,\n\tDeviceInfo,\n\tDeviceRemoveCallback,\n\tListenerConfig,\n\tUsbDeviceListenerI,\n} from \"./types\";\n\ninterface NativeAddon {\n\tstartListening(): void;\n\tstopListening(): void;\n\tonDeviceAdd(callback: DeviceAddCallback): void;\n\tonDeviceRemove(callback: DeviceRemoveCallback): void;\n\tlistDevices(): DeviceInfo[];\n}\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\n// Load native addon using require (CJS) from ESM context\nconst require = createRequire(import.meta.url);\nconst packageRoot = path.join(__dirname, \"..\");\nconst addon: NativeAddon = require(\"node-gyp-build\")(packageRoot);\n\nconst { listDevices, onDeviceAdd, onDeviceRemove, startListening, stopListening } = addon;\n\n/**\n * USB Device Listener implementation\n * Provides a type-safe wrapper around the native C++ addon\n */\nexport default class UsbDeviceListener implements UsbDeviceListenerI {\n\tprivate config: ListenerConfig = {};\n\tprivate userAddCallback: DeviceAddCallback | null = null;\n\tprivate userRemoveCallback: DeviceRemoveCallback | null = null;\n\n\t/**\n\t * Start listening for USB device events\n\t */\n\tpublic startListening(config: ListenerConfig): void {\n\t\tif (typeof config !== \"object\" || config === null) {\n\t\t\tthrow new TypeError(\"Config must be an object\");\n\t\t}\n\t\tthis.config = config;\n\t\tstartListening();\n\t}\n\n\t/**\n\t * Stop listening for USB device events\n\t */\n\tpublic stopListening(): void {\n\t\tstopListening();\n\t}\n\n\t/**\n\t * Register callback for device connection events\n\t */\n\tpublic onDeviceAdd(callback: DeviceAddCallback): void {\n\t\tif (typeof callback !== \"function\") {\n\t\t\tthrow new TypeError(\"Callback must be a function\");\n\t\t}\n\t\tthis.userAddCallback = callback;\n\n\t\t// Set up internal callback that filters devices\n\t\tonDeviceAdd((device: DeviceInfo) => {\n\t\t\tif (shouldNotifyDevice(device, this.config)) {\n\t\t\t\tconst enrichedDevice = applyLogicalPortMapping(device, this.config);\n\t\t\t\tthis.userAddCallback?.(enrichedDevice);\n\t\t\t}\n\t\t});\n\t}\n\n\t/**\n\t * Register callback for device disconnection events\n\t */\n\tpublic onDeviceRemove(callback: DeviceRemoveCallback): void {\n\t\tif (typeof callback !== \"function\") {\n\t\t\tthrow new TypeError(\"Callback must be a function\");\n\t\t}\n\t\tthis.userRemoveCallback = callback;\n\n\t\t// Set up internal callback that filters devices\n\t\tonDeviceRemove((device: DeviceInfo) => {\n\t\t\tif (shouldNotifyDevice(device, this.config)) {\n\t\t\t\tconst enrichedDevice = applyLogicalPortMapping(device, this.config);\n\t\t\t\tthis.userRemoveCallback?.(enrichedDevice);\n\t\t\t}\n\t\t});\n\t}\n\n\t/**\n\t * List all currently connected USB devices\n\t */\n\tpublic listDevices(): DeviceInfo[] {\n\t\treturn listDevices();\n\t}\n}\n\nexport type {\n\tDeviceInfo,\n\tDeviceAddCallback,\n\tDeviceRemoveCallback,\n\tListenerConfig,\n\tTargetDevice,\n} from \"./types\";\n", "import type { DeviceInfo, ListenerConfig, TargetDevice } from \"./types\";\n\n/**\n * Convert a decimal VID/PID to uppercase hex string for comparison\n */\nfunction toHexString(value: number): string {\n\treturn value.toString(16).toUpperCase().padStart(4, \"0\");\n}\n\n/**\n * Check if a device matches a target device filter by VID/PID\n */\nfunction matchesDevice(device: DeviceInfo, target: TargetDevice): boolean {\n\tconst deviceVid = toHexString(device.vid);\n\tconst devicePid = toHexString(device.pid);\n\tconst targetVid = target.vid.toUpperCase();\n\tconst targetPid = target.pid.toUpperCase();\n\n\treturn deviceVid === targetVid && devicePid === targetPid;\n}\n\n/**\n * Check if a device matches any device in a list of target devices\n */\nfunction matchesAnyDevice(device: DeviceInfo, targets: TargetDevice[]): boolean {\n\treturn targets.some((target) => matchesDevice(device, target));\n}\n\n/**\n * Determine if a device notification should be sent based on the configuration.\n *\n * Filter priority (highest to lowest):\n * 1. ignoredDevices - if device matches, always return false\n * 2. listenOnlyDevices - if specified, device must match at least one\n * 3. targetDevices - if specified, device must match at least one\n * 4. logicalPortMap - if specified, device location must be in the map\n *\n * @param device - The device information from the native addon\n * @param config - The listener configuration\n * @returns true if the device should trigger a notification, false otherwise\n */\nexport function shouldNotifyDevice(device: DeviceInfo, config: ListenerConfig): boolean {\n\t// Priority 1: Check ignoredDevices (highest priority - always blocks)\n\tif (config.ignoredDevices && config.ignoredDevices.length > 0) {\n\t\tif (matchesAnyDevice(device, config.ignoredDevices)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// Priority 2: Check listenOnlyDevices (if specified, device must match)\n\tif (config.listenOnlyDevices && config.listenOnlyDevices.length > 0) {\n\t\tif (!matchesAnyDevice(device, config.listenOnlyDevices)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// Priority 3: Check targetDevices (if specified, device must match)\n\tif (config.targetDevices && config.targetDevices.length > 0) {\n\t\tif (!matchesAnyDevice(device, config.targetDevices)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// Priority 4: Check logicalPortMap (if specified, device must be mapped)\n\tif (config.logicalPortMap && Object.keys(config.logicalPortMap).length > 0) {\n\t\tif (!(device.locationInfo in config.logicalPortMap)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\treturn true;\n}\n\n/**\n * Apply logical port mapping to a device if configured\n *\n * @param device - The device information from the native addon\n * @param config - The listener configuration\n * @returns Device info with logicalPort set if mapped, otherwise unchanged\n */\nexport function applyLogicalPortMapping(device: DeviceInfo, config: ListenerConfig): DeviceInfo {\n\tif (config.logicalPortMap && device.locationInfo in config.logicalPortMap) {\n\t\treturn {\n\t\t\t...device,\n\t\t\tlogicalPort: config.logicalPortMap[device.locationInfo],\n\t\t};\n\t}\n\treturn device;\n}\n"],
+  "mappings": "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",
+  "names": ["path", "require"]
+}

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts", "../src/device-filter.ts"],
-  "sourcesContent": ["import { createRequire } from \"node:module\";\r\nimport path from \"node:path\";\r\nimport { fileURLToPath } from \"node:url\";\r\nimport { applyLogicalPortMapping, shouldNotifyDevice } from \"./device-filter\";\r\nimport type {\r\n\tDeviceAddCallback,\r\n\tDeviceInfo,\r\n\tDeviceRemoveCallback,\r\n\tListenerConfig,\r\n\tUsbDeviceListenerI,\r\n} from \"./types\";\r\n\r\ninterface NativeAddon {\r\n\tstartListening(): void;\r\n\tstopListening(): void;\r\n\tonDeviceAdd(callback: DeviceAddCallback): void;\r\n\tonDeviceRemove(callback: DeviceRemoveCallback): void;\r\n\tlistDevices(): DeviceInfo[];\r\n}\r\n\r\nconst __filename = fileURLToPath(import.meta.url);\r\nconst __dirname = path.dirname(__filename);\r\n\r\n// Load native addon using require (CJS) from ESM context\r\nconst require = createRequire(import.meta.url);\r\nconst packageRoot = path.join(__dirname, \"..\");\r\nconst addon: NativeAddon = require(\"node-gyp-build\")(packageRoot);\r\n\r\nconst { listDevices, onDeviceAdd, onDeviceRemove, startListening, stopListening } = addon;\r\n\r\n/**\r\n * USB Device Listener implementation\r\n * Provides a type-safe wrapper around the native C++ addon\r\n */\r\nexport default class UsbDeviceListener implements UsbDeviceListenerI {\r\n\tprivate config: ListenerConfig = {};\r\n\tprivate userAddCallback: DeviceAddCallback | null = null;\r\n\tprivate userRemoveCallback: DeviceRemoveCallback | null = null;\r\n\r\n\t/**\r\n\t * Start listening for USB device events\r\n\t */\r\n\tpublic startListening(config: ListenerConfig): void {\r\n\t\tif (typeof config !== \"object\" || config === null) {\r\n\t\t\tthrow new TypeError(\"Config must be an object\");\r\n\t\t}\r\n\t\tthis.config = config;\r\n\t\tstartListening();\r\n\t}\r\n\r\n\t/**\r\n\t * Stop listening for USB device events\r\n\t */\r\n\tpublic stopListening(): void {\r\n\t\tstopListening();\r\n\t}\r\n\r\n\t/**\r\n\t * Register callback for device connection events\r\n\t */\r\n\tpublic onDeviceAdd(callback: DeviceAddCallback): void {\r\n\t\tif (typeof callback !== \"function\") {\r\n\t\t\tthrow new TypeError(\"Callback must be a function\");\r\n\t\t}\r\n\t\tthis.userAddCallback = callback;\r\n\r\n\t\t// Set up internal callback that filters devices\r\n\t\tonDeviceAdd((device: DeviceInfo) => {\r\n\t\t\tif (shouldNotifyDevice(device, this.config)) {\r\n\t\t\t\tconst enrichedDevice = applyLogicalPortMapping(device, this.config);\r\n\t\t\t\tthis.userAddCallback?.(enrichedDevice);\r\n\t\t\t}\r\n\t\t});\r\n\t}\r\n\r\n\t/**\r\n\t * Register callback for device disconnection events\r\n\t */\r\n\tpublic onDeviceRemove(callback: DeviceRemoveCallback): void {\r\n\t\tif (typeof callback !== \"function\") {\r\n\t\t\tthrow new TypeError(\"Callback must be a function\");\r\n\t\t}\r\n\t\tthis.userRemoveCallback = callback;\r\n\r\n\t\t// Set up internal callback that filters devices\r\n\t\tonDeviceRemove((device: DeviceInfo) => {\r\n\t\t\tif (shouldNotifyDevice(device, this.config)) {\r\n\t\t\t\tconst enrichedDevice = applyLogicalPortMapping(device, this.config);\r\n\t\t\t\tthis.userRemoveCallback?.(enrichedDevice);\r\n\t\t\t}\r\n\t\t});\r\n\t}\r\n\r\n\t/**\r\n\t * List all currently connected USB devices\r\n\t */\r\n\tpublic listDevices(): DeviceInfo[] {\r\n\t\treturn listDevices();\r\n\t}\r\n}\r\n\r\nexport type {\r\n\tDeviceInfo,\r\n\tDeviceAddCallback,\r\n\tDeviceRemoveCallback,\r\n\tListenerConfig,\r\n\tTargetDevice,\r\n} from \"./types\";\r\n", "import type { DeviceInfo, ListenerConfig, TargetDevice } from \"./types\";\n\n/**\n * Convert a decimal VID/PID to uppercase hex string for comparison\n */\nfunction toHexString(value: number): string {\n\treturn value.toString(16).toUpperCase().padStart(4, \"0\");\n}\n\n/**\n * Check if a device matches a target device filter by VID/PID\n */\nfunction matchesDevice(device: DeviceInfo, target: TargetDevice): boolean {\n\tconst deviceVid = toHexString(device.vid);\n\tconst devicePid = toHexString(device.pid);\n\tconst targetVid = target.vid.toUpperCase();\n\tconst targetPid = target.pid.toUpperCase();\n\n\treturn deviceVid === targetVid && devicePid === targetPid;\n}\n\n/**\n * Check if a device matches any device in a list of target devices\n */\nfunction matchesAnyDevice(device: DeviceInfo, targets: TargetDevice[]): boolean {\n\treturn targets.some((target) => matchesDevice(device, target));\n}\n\n/**\n * Determine if a device notification should be sent based on the configuration.\n *\n * Filter priority (highest to lowest):\n * 1. ignoredDevices - if device matches, always return false\n * 2. listenOnlyDevices - if specified, device must match at least one\n * 3. targetDevices - if specified, device must match at least one\n * 4. logicalPortMap - if specified, device location must be in the map\n *\n * @param device - The device information from the native addon\n * @param config - The listener configuration\n * @returns true if the device should trigger a notification, false otherwise\n */\nexport function shouldNotifyDevice(device: DeviceInfo, config: ListenerConfig): boolean {\n\t// Priority 1: Check ignoredDevices (highest priority - always blocks)\n\tif (config.ignoredDevices && config.ignoredDevices.length > 0) {\n\t\tif (matchesAnyDevice(device, config.ignoredDevices)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// Priority 2: Check listenOnlyDevices (if specified, device must match)\n\tif (config.listenOnlyDevices && config.listenOnlyDevices.length > 0) {\n\t\tif (!matchesAnyDevice(device, config.listenOnlyDevices)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// Priority 3: Check targetDevices (if specified, device must match)\n\tif (config.targetDevices && config.targetDevices.length > 0) {\n\t\tif (!matchesAnyDevice(device, config.targetDevices)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// Priority 4: Check logicalPortMap (if specified, device must be mapped)\n\tif (config.logicalPortMap && Object.keys(config.logicalPortMap).length > 0) {\n\t\tif (!(device.locationInfo in config.logicalPortMap)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\treturn true;\n}\n\n/**\n * Apply logical port mapping to a device if configured\n *\n * @param device - The device information from the native addon\n * @param config - The listener configuration\n * @returns Device info with logicalPort set if mapped, otherwise unchanged\n */\nexport function applyLogicalPortMapping(device: DeviceInfo, config: ListenerConfig): DeviceInfo {\n\tif (config.logicalPortMap && device.locationInfo in config.logicalPortMap) {\n\t\treturn {\n\t\t\t...device,\n\t\t\tlogicalPort: config.logicalPortMap[device.locationInfo],\n\t\t};\n\t}\n\treturn device;\n}\n"],
+  "sourcesContent": ["import { createRequire } from \"node:module\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { applyLogicalPortMapping, shouldNotifyDevice } from \"./device-filter\";\nimport type {\n\tDeviceAddCallback,\n\tDeviceInfo,\n\tDeviceRemoveCallback,\n\tListenerConfig,\n\tUsbDeviceListenerI,\n} from \"./types\";\n\ninterface NativeAddon {\n\tstartListening(): void;\n\tstopListening(): void;\n\tonDeviceAdd(callback: DeviceAddCallback): void;\n\tonDeviceRemove(callback: DeviceRemoveCallback): void;\n\tlistDevices(): DeviceInfo[];\n}\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\n// Load native addon using require (CJS) from ESM context\nconst require = createRequire(import.meta.url);\nconst packageRoot = path.join(__dirname, \"..\");\nconst addon: NativeAddon = require(\"node-gyp-build\")(packageRoot);\n\nconst { listDevices, onDeviceAdd, onDeviceRemove, startListening, stopListening } = addon;\n\n/**\n * USB Device Listener implementation\n * Provides a type-safe wrapper around the native C++ addon\n */\nexport default class UsbDeviceListener implements UsbDeviceListenerI {\n\tprivate config: ListenerConfig = {};\n\tprivate userAddCallback: DeviceAddCallback | null = null;\n\tprivate userRemoveCallback: DeviceRemoveCallback | null = null;\n\n\t/**\n\t * Start listening for USB device events\n\t */\n\tpublic startListening(config: ListenerConfig): void {\n\t\tif (typeof config !== \"object\" || config === null) {\n\t\t\tthrow new TypeError(\"Config must be an object\");\n\t\t}\n\t\tthis.config = config;\n\t\tstartListening();\n\t}\n\n\t/**\n\t * Stop listening for USB device events\n\t */\n\tpublic stopListening(): void {\n\t\tstopListening();\n\t}\n\n\t/**\n\t * Register callback for device connection events\n\t */\n\tpublic onDeviceAdd(callback: DeviceAddCallback): void {\n\t\tif (typeof callback !== \"function\") {\n\t\t\tthrow new TypeError(\"Callback must be a function\");\n\t\t}\n\t\tthis.userAddCallback = callback;\n\n\t\t// Set up internal callback that filters devices\n\t\tonDeviceAdd((device: DeviceInfo) => {\n\t\t\tif (shouldNotifyDevice(device, this.config)) {\n\t\t\t\tconst enrichedDevice = applyLogicalPortMapping(device, this.config);\n\t\t\t\tthis.userAddCallback?.(enrichedDevice);\n\t\t\t}\n\t\t});\n\t}\n\n\t/**\n\t * Register callback for device disconnection events\n\t */\n\tpublic onDeviceRemove(callback: DeviceRemoveCallback): void {\n\t\tif (typeof callback !== \"function\") {\n\t\t\tthrow new TypeError(\"Callback must be a function\");\n\t\t}\n\t\tthis.userRemoveCallback = callback;\n\n\t\t// Set up internal callback that filters devices\n\t\tonDeviceRemove((device: DeviceInfo) => {\n\t\t\tif (shouldNotifyDevice(device, this.config)) {\n\t\t\t\tconst enrichedDevice = applyLogicalPortMapping(device, this.config);\n\t\t\t\tthis.userRemoveCallback?.(enrichedDevice);\n\t\t\t}\n\t\t});\n\t}\n\n\t/**\n\t * List all currently connected USB devices\n\t */\n\tpublic listDevices(): DeviceInfo[] {\n\t\treturn listDevices();\n\t}\n}\n\nexport type {\n\tDeviceInfo,\n\tDeviceAddCallback,\n\tDeviceRemoveCallback,\n\tListenerConfig,\n\tTargetDevice,\n} from \"./types\";\n", "import type { DeviceInfo, ListenerConfig, TargetDevice } from \"./types\";\n\n/**\n * Convert a decimal VID/PID to uppercase hex string for comparison\n */\nfunction toHexString(value: number): string {\n\treturn value.toString(16).toUpperCase().padStart(4, \"0\");\n}\n\n/**\n * Check if a device matches a target device filter by VID/PID\n */\nfunction matchesDevice(device: DeviceInfo, target: TargetDevice): boolean {\n\tconst deviceVid = toHexString(device.vid);\n\tconst devicePid = toHexString(device.pid);\n\tconst targetVid = target.vid.toUpperCase();\n\tconst targetPid = target.pid.toUpperCase();\n\n\treturn deviceVid === targetVid && devicePid === targetPid;\n}\n\n/**\n * Check if a device matches any device in a list of target devices\n */\nfunction matchesAnyDevice(device: DeviceInfo, targets: TargetDevice[]): boolean {\n\treturn targets.some((target) => matchesDevice(device, target));\n}\n\n/**\n * Determine if a device notification should be sent based on the configuration.\n *\n * Filter priority (highest to lowest):\n * 1. ignoredDevices - if device matches, always return false\n * 2. listenOnlyDevices - if specified, device must match at least one\n * 3. targetDevices - if specified, device must match at least one\n * 4. logicalPortMap - if specified, device location must be in the map\n *\n * @param device - The device information from the native addon\n * @param config - The listener configuration\n * @returns true if the device should trigger a notification, false otherwise\n */\nexport function shouldNotifyDevice(device: DeviceInfo, config: ListenerConfig): boolean {\n\t// Priority 1: Check ignoredDevices (highest priority - always blocks)\n\tif (config.ignoredDevices && config.ignoredDevices.length > 0) {\n\t\tif (matchesAnyDevice(device, config.ignoredDevices)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// Priority 2: Check listenOnlyDevices (if specified, device must match)\n\tif (config.listenOnlyDevices && config.listenOnlyDevices.length > 0) {\n\t\tif (!matchesAnyDevice(device, config.listenOnlyDevices)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// Priority 3: Check targetDevices (if specified, device must match)\n\tif (config.targetDevices && config.targetDevices.length > 0) {\n\t\tif (!matchesAnyDevice(device, config.targetDevices)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// Priority 4: Check logicalPortMap (if specified, device must be mapped)\n\tif (config.logicalPortMap && Object.keys(config.logicalPortMap).length > 0) {\n\t\tif (!(device.locationInfo in config.logicalPortMap)) {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\treturn true;\n}\n\n/**\n * Apply logical port mapping to a device if configured\n *\n * @param device - The device information from the native addon\n * @param config - The listener configuration\n * @returns Device info with logicalPort set if mapped, otherwise unchanged\n */\nexport function applyLogicalPortMapping(device: DeviceInfo, config: ListenerConfig): DeviceInfo {\n\tif (config.logicalPortMap && device.locationInfo in config.logicalPortMap) {\n\t\treturn {\n\t\t\t...device,\n\t\t\tlogicalPort: config.logicalPortMap[device.locationInfo],\n\t\t};\n\t}\n\treturn device;\n}\n"],
   "mappings": "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",
   "names": ["require"]
 }

package/native/addon.cc

@@ -0,0 +1,118 @@
+#include <napi.h>
+#include "usb_listener.h"
+#include <memory>
+
+static std::unique_ptr<USBListener> g_listener;
+
+Napi::Value StartListening(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	
+	if (!g_listener) {
+		g_listener = std::make_unique<USBListener>();
+	}
+	
+	std::string errorMsg;
+	if (!g_listener->StartListening(errorMsg)) {
+		Napi::Error::New(env, errorMsg).ThrowAsJavaScriptException();
+		return env.Undefined();
+	}
+	
+	return env.Undefined();
+}
+
+Napi::Value StopListening(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	
+	if (g_listener) {
+		g_listener->StopListening();
+	}
+	
+	return env.Undefined();
+}
+
+Napi::Value OnDeviceAdd(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	
+	if (info.Length() < 1 || !info[0].IsFunction()) {
+		Napi::TypeError::New(env, "Callback function expected").ThrowAsJavaScriptException();
+		return env.Undefined();
+	}
+	
+	Napi::Function callback = info[0].As<Napi::Function>();
+	
+	if (!g_listener) {
+		g_listener = std::make_unique<USBListener>();
+	}
+	
+	Napi::ThreadSafeFunction tsfn = Napi::ThreadSafeFunction::New(
+		env,
+		callback,
+		"DeviceAddCallback",
+		0,
+		1
+	);
+	
+	g_listener->SetAddCallback(tsfn);
+	
+	return env.Undefined();
+}
+
+Napi::Value OnDeviceRemove(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	
+	if (info.Length() < 1 || !info[0].IsFunction()) {
+		Napi::TypeError::New(env, "Callback function expected").ThrowAsJavaScriptException();
+		return env.Undefined();
+	}
+	
+	Napi::Function callback = info[0].As<Napi::Function>();
+	
+	if (!g_listener) {
+		g_listener = std::make_unique<USBListener>();
+	}
+	
+	Napi::ThreadSafeFunction tsfn = Napi::ThreadSafeFunction::New(
+		env,
+		callback,
+		"DeviceRemoveCallback",
+		0,
+		1
+	);
+	
+	g_listener->SetRemoveCallback(tsfn);
+	
+	return env.Undefined();
+}
+
+Napi::Value ListDevices(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	
+	if (!g_listener) {
+		g_listener = std::make_unique<USBListener>();
+	}
+	
+	std::vector<DeviceInfo> devices = g_listener->ListAllDevices();
+	
+	Napi::Array result = Napi::Array::New(env, devices.size());
+	for (size_t i = 0; i < devices.size(); i++) {
+		Napi::Object obj = Napi::Object::New(env);
+		obj.Set("deviceId", Napi::String::New(env, devices[i].deviceId));
+		obj.Set("vid", Napi::Number::New(env, devices[i].vid));
+		obj.Set("pid", Napi::Number::New(env, devices[i].pid));
+		obj.Set("locationInfo", Napi::String::New(env, devices[i].locationInfo));
+		result[i] = obj;
+	}
+	
+	return result;
+}
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+	exports.Set("startListening", Napi::Function::New(env, StartListening));
+	exports.Set("stopListening", Napi::Function::New(env, StopListening));
+	exports.Set("onDeviceAdd", Napi::Function::New(env, OnDeviceAdd));
+	exports.Set("onDeviceRemove", Napi::Function::New(env, OnDeviceRemove));
+	exports.Set("listDevices", Napi::Function::New(env, ListDevices));
+	return exports;
+}
+
+NODE_API_MODULE(usb_device_listener, Init)

package/native/usb_listener.cc

@@ -0,0 +1,414 @@
+#include "usb_listener.h"
+#include <devguid.h>
+#include <usbiodef.h>  // For GUID_DEVINTERFACE_USB_DEVICE
+#include <sstream>
+#include <iomanip>
+#include <algorithm>
+
+USBListener::USBListener() = default;
+
+USBListener::~USBListener() {
+	StopListening();
+}
+
+/**
+ * Start the USB device listener
+ * Creates a separate thread that runs a Windows message loop to receive device notifications
+ */
+bool USBListener::StartListening(std::string& errorMsg) {
+	bool expected = false;
+	if (!m_running.compare_exchange_strong(expected, true)) {
+		errorMsg = "Listener already running";
+		return false;
+	}
+	
+	// Create thread with RAII wrapper
+	HANDLE threadHandle = CreateThread(nullptr, 0, ListenerThreadProc, this, 0, nullptr);
+	if (!threadHandle) {
+		m_running = false;
+		errorMsg = "Failed to create listener thread";
+		return false;
+	}
+	m_thread = ThreadHandle(threadHandle);
+	
+	// Brief wait for thread initialization
+	Sleep(100);
+	EnumerateConnectedDevices();
+	
+	return true;
+}
+
+void USBListener::StopListening() {
+	bool expected = true;
+	if (!m_running.compare_exchange_strong(expected, false)) {
+		return;  // Already stopped
+	}
+	
+	// Signal message loop to quit
+	if (m_hwnd) {
+		PostMessage(m_hwnd, WM_QUIT, 0, 0);
+	}
+	
+	// Thread cleanup is automatic via ThreadHandle RAII
+	// Destructor will wait and close handle
+	m_thread = ThreadHandle();  // Reset to trigger cleanup
+	
+	// Release ThreadSafeFunction callbacks
+	if (m_addCallback) {
+		m_addCallback.Release();
+	}
+	if (m_removeCallback) {
+		m_removeCallback.Release();
+	}
+	
+	// Clear device cache
+	std::unique_lock lock(m_cacheMutex);
+	m_deviceCache.clear();
+}
+
+void USBListener::SetAddCallback(Napi::ThreadSafeFunction callback) {
+	m_addCallback = callback;
+}
+
+void USBListener::SetRemoveCallback(Napi::ThreadSafeFunction callback) {
+	m_removeCallback = callback;
+}
+
+DWORD WINAPI USBListener::ListenerThreadProc(LPVOID param) {
+	USBListener* listener = static_cast<USBListener*>(param);
+	listener->MessageLoop();
+	return 0;
+}
+
+void USBListener::MessageLoop() {
+	WNDCLASSEX wc = {0};
+	wc.cbSize = sizeof(WNDCLASSEX);
+	wc.lpfnWndProc = WindowProc;
+	wc.hInstance = GetModuleHandle(nullptr);
+	wc.lpszClassName = L"USBListenerWindow";
+	
+	if (!RegisterClassEx(&wc)) {
+		return;
+	}
+	
+	m_hwnd = CreateWindowEx(0, L"USBListenerWindow", L"USBListener", 0, 0, 0, 0, 0, HWND_MESSAGE, nullptr, GetModuleHandle(nullptr), nullptr);
+	if (!m_hwnd) {
+		return;
+	}
+	
+	SetWindowLongPtr(m_hwnd, GWLP_USERDATA, reinterpret_cast<LONG_PTR>(this));
+	
+	DEV_BROADCAST_DEVICEINTERFACE notificationFilter = {0};
+	notificationFilter.dbcc_size = sizeof(DEV_BROADCAST_DEVICEINTERFACE);
+	notificationFilter.dbcc_devicetype = DBT_DEVTYP_DEVICEINTERFACE;
+	notificationFilter.dbcc_classguid = GUID_DEVINTERFACE_USB_DEVICE;
+	
+	m_notifyHandle = RegisterDeviceNotification(m_hwnd, &notificationFilter, DEVICE_NOTIFY_WINDOW_HANDLE);
+	
+	MSG msg;
+	while (m_running && GetMessage(&msg, nullptr, 0, 0)) {
+		TranslateMessage(&msg);
+		DispatchMessage(&msg);
+	}
+	
+	if (m_notifyHandle) {
+		UnregisterDeviceNotification(m_notifyHandle);
+		m_notifyHandle = nullptr;
+	}
+	
+	if (m_hwnd) {
+		DestroyWindow(m_hwnd);
+		m_hwnd = nullptr;
+	}
+	
+	UnregisterClass(L"USBListenerWindow", GetModuleHandle(nullptr));
+}
+
+LRESULT CALLBACK USBListener::WindowProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) {
+	if (msg == WM_DEVICECHANGE) {
+		USBListener* listener = reinterpret_cast<USBListener*>(GetWindowLongPtr(hwnd, GWLP_USERDATA));
+		if (listener) {
+			listener->HandleDeviceChange(wParam, lParam);
+		}
+	}
+	return DefWindowProc(hwnd, msg, wParam, lParam);
+}
+
+/**
+ * Handle WM_DEVICECHANGE messages
+ * For connections: queries Windows API for full device info
+ * For disconnections: retrieves cached info since device is already gone
+ */
+void USBListener::HandleDeviceChange(WPARAM wParam, LPARAM lParam) {
+	// Only handle device arrival and removal events
+	if (wParam != DBT_DEVICEARRIVAL && wParam != DBT_DEVICEREMOVECOMPLETE) {
+		return;
+	}
+	
+	// Extract device interface information
+	DEV_BROADCAST_DEVICEINTERFACE* devInterface = reinterpret_cast<DEV_BROADCAST_DEVICEINTERFACE*>(lParam);
+	if (!devInterface || devInterface->dbcc_devicetype != DBT_DEVTYP_DEVICEINTERFACE) {
+		return;
+	}
+	
+	// Convert device path to string
+	std::wstring devicePathW = devInterface->dbcc_name;
+	std::string devicePath(devicePathW.begin(), devicePathW.end());
+	
+	DeviceInfo info;
+	bool gotInfo = false;
+	
+	if (wParam == DBT_DEVICEARRIVAL) {
+		// For connections, query Windows API for full device details
+		gotInfo = GetDeviceInfo(devicePath, info);
+	} else if (wParam == DBT_DEVICEREMOVECOMPLETE) {
+		// For disconnections, device is gone - retrieve from cache
+		DeviceInfo pathInfo;
+		if (GetDeviceInfoFromPath(devicePath, pathInfo)) {
+			std::unique_lock lock(m_cacheMutex);  // Exclusive lock for write
+			if (auto it = m_deviceCache.find(pathInfo.deviceId); it != m_deviceCache.end()) {
+				info = std::move(it->second);  // Move for efficiency
+				m_deviceCache.erase(it);
+				gotInfo = true;
+			}
+		}
+	}
+	
+	if (!gotInfo) {
+		return;
+	}
+	
+	if (wParam == DBT_DEVICEARRIVAL && m_addCallback) {
+		// Cache device info for disconnect events
+		{
+			std::unique_lock lock(m_cacheMutex);  // Exclusive lock for write
+			m_deviceCache[info.deviceId] = info;
+		}
+		auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
+			Napi::Object obj = Napi::Object::New(env);
+			obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+			obj.Set("vid", Napi::Number::New(env, data->vid));
+			obj.Set("pid", Napi::Number::New(env, data->pid));
+			obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
+			if (data->logicalPort >= 0) {
+				obj.Set("logicalPort", Napi::Number::New(env, data->logicalPort));
+			} else {
+				obj.Set("logicalPort", env.Null());
+			}
+			jsCallback.Call({obj});
+			delete data;
+		};
+		m_addCallback.BlockingCall(new DeviceInfo(info), callback);
+	} else if (wParam == DBT_DEVICEREMOVECOMPLETE && m_removeCallback) {
+		auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
+			Napi::Object obj = Napi::Object::New(env);
+			obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+			obj.Set("vid", Napi::Number::New(env, data->vid));
+			obj.Set("pid", Napi::Number::New(env, data->pid));
+			obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
+			if (data->logicalPort >= 0) {
+				obj.Set("logicalPort", Napi::Number::New(env, data->logicalPort));
+			} else {
+				obj.Set("logicalPort", env.Null());
+			}
+			jsCallback.Call({obj});
+			delete data;
+		};
+		m_removeCallback.BlockingCall(new DeviceInfo(info), callback);
+	}
+}
+
+bool USBListener::GetDeviceInfoFromPath(const std::string& devicePath, DeviceInfo& info) {
+	size_t hashPos = devicePath.rfind('#');
+	if (hashPos == std::string::npos) {
+		return false;
+	}
+	
+	std::string deviceIdStr = devicePath.substr(4, hashPos - 4);
+	std::replace(deviceIdStr.begin(), deviceIdStr.end(), '#', '\\');
+	
+	info.deviceId = deviceIdStr;
+	
+	if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+		return false;
+	}
+	
+	size_t lastHash = deviceIdStr.rfind('\\');
+	if (lastHash != std::string::npos) {
+		info.locationInfo = deviceIdStr.substr(lastHash + 1);
+	} else {
+		info.locationInfo = "";
+	}
+	
+	return true;
+}
+
+bool USBListener::GetDeviceInfo(const std::string& devicePath, DeviceInfo& info) {
+	size_t hashPos = devicePath.rfind('#');
+	if (hashPos == std::string::npos) {
+		return false;
+	}
+	
+	std::string deviceIdStr = devicePath.substr(4, hashPos - 4);
+	std::replace(deviceIdStr.begin(), deviceIdStr.end(), '#', '\\');
+	
+	std::wstring deviceIdW(deviceIdStr.begin(), deviceIdStr.end());
+	
+	HDEVINFO deviceInfoSet = SetupDiGetClassDevs(&GUID_DEVINTERFACE_USB_DEVICE, nullptr, nullptr, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
+	if (deviceInfoSet == INVALID_HANDLE_VALUE) {
+		return false;
+	}
+	
+	SP_DEVINFO_DATA devInfoData = {0};
+	devInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
+	
+	for (DWORD i = 0; SetupDiEnumDeviceInfo(deviceInfoSet, i, &devInfoData); i++) {
+		WCHAR instanceId[MAX_PATH];
+		if (SetupDiGetDeviceInstanceId(deviceInfoSet, &devInfoData, instanceId, MAX_PATH, nullptr)) {
+			if (_wcsicmp(instanceId, deviceIdW.c_str()) == 0) {
+				std::wstring idW = instanceId;
+				info.deviceId = std::string(idW.begin(), idW.end());
+				
+				if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+					SetupDiDestroyDeviceInfoList(deviceInfoSet);
+					return false;
+				}
+				
+				DEVINST devInst = devInfoData.DevInst;
+				if (!GetLocationInfo(devInst, info.locationInfo)) {
+					SetupDiDestroyDeviceInfoList(deviceInfoSet);
+					return false;
+				}
+				
+				SetupDiDestroyDeviceInfoList(deviceInfoSet);
+				return true;
+			}
+		}
+	}
+	
+	SetupDiDestroyDeviceInfoList(deviceInfoSet);
+	return false;
+}
+
+bool USBListener::GetLocationInfo(DEVINST devInst, std::string& locationInfo) {
+	WCHAR buffer[MAX_PATH];
+	ULONG size = sizeof(buffer);
+	
+	CONFIGRET ret = CM_Get_DevNode_Registry_Property(devInst, CM_DRP_LOCATION_INFORMATION, nullptr, buffer, &size, 0);
+	if (ret != CR_SUCCESS) {
+		return false;
+	}
+	
+	std::wstring locationW = buffer;
+	locationInfo = std::string(locationW.begin(), locationW.end());
+	return true;
+}
+
+bool USBListener::GetVidPid(const std::string& deviceId, uint16_t& vid, uint16_t& pid) {
+	size_t vidPos = deviceId.find("VID_");
+	size_t pidPos = deviceId.find("PID_");
+	
+	if (vidPos == std::string::npos || pidPos == std::string::npos) {
+		return false;
+	}
+	
+	try {
+		std::string vidStr = deviceId.substr(vidPos + 4, 4);
+		std::string pidStr = deviceId.substr(pidPos + 4, 4);
+		
+		vid = static_cast<uint16_t>(std::stoul(vidStr, nullptr, 16));
+		pid = static_cast<uint16_t>(std::stoul(pidStr, nullptr, 16));
+		return true;
+	} catch (...) {
+		return false;
+	}
+}
+
+void USBListener::EnumerateConnectedDevices() {
+	HDEVINFO deviceInfoSet = SetupDiGetClassDevs(&GUID_DEVINTERFACE_USB_DEVICE, nullptr, nullptr, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
+	if (deviceInfoSet == INVALID_HANDLE_VALUE) {
+		return;
+	}
+	
+	SP_DEVINFO_DATA devInfoData = {0};
+	devInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
+	
+	for (DWORD i = 0; SetupDiEnumDeviceInfo(deviceInfoSet, i, &devInfoData); i++) {
+		WCHAR instanceId[MAX_PATH];
+		if (SetupDiGetDeviceInstanceId(deviceInfoSet, &devInfoData, instanceId, MAX_PATH, nullptr)) {
+			DeviceInfo info;
+			std::wstring idW = instanceId;
+			info.deviceId = std::string(idW.begin(), idW.end());
+			
+			if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+				continue;
+			}
+			
+			DEVINST devInst = devInfoData.DevInst;
+			if (!GetLocationInfo(devInst, info.locationInfo)) {
+				continue;
+			}
+			
+			// Cache device with exclusive lock
+			{
+				std::unique_lock lock(m_cacheMutex);
+				m_deviceCache[info.deviceId] = info;
+			}
+			
+			if (m_addCallback) {
+				auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
+					Napi::Object obj = Napi::Object::New(env);
+					obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+					obj.Set("vid", Napi::Number::New(env, data->vid));
+					obj.Set("pid", Napi::Number::New(env, data->pid));
+					obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
+					if (data->logicalPort >= 0) {
+						obj.Set("logicalPort", Napi::Number::New(env, data->logicalPort));
+					} else {
+						obj.Set("logicalPort", env.Null());
+					}
+					jsCallback.Call({obj});
+					delete data;
+				};
+				m_addCallback.BlockingCall(new DeviceInfo(info), callback);
+			}
+		}
+	}
+	
+	SetupDiDestroyDeviceInfoList(deviceInfoSet);
+}
+
+std::vector<DeviceInfo> USBListener::ListAllDevices() {
+	std::vector<DeviceInfo> devices;
+	
+	HDEVINFO deviceInfoSet = SetupDiGetClassDevs(&GUID_DEVINTERFACE_USB_DEVICE, nullptr, nullptr, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
+	if (deviceInfoSet == INVALID_HANDLE_VALUE) {
+		return devices;
+	}
+	
+	SP_DEVINFO_DATA devInfoData = {0};
+	devInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
+	
+	for (DWORD i = 0; SetupDiEnumDeviceInfo(deviceInfoSet, i, &devInfoData); i++) {
+		WCHAR instanceId[MAX_PATH];
+		if (SetupDiGetDeviceInstanceId(deviceInfoSet, &devInfoData, instanceId, MAX_PATH, nullptr)) {
+			DeviceInfo info;
+			std::wstring idW = instanceId;
+			info.deviceId = std::string(idW.begin(), idW.end());
+			
+			if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+				continue;
+			}
+			
+			DEVINST devInst = devInfoData.DevInst;
+			if (!GetLocationInfo(devInst, info.locationInfo)) {
+				continue;
+			}
+			
+			devices.push_back(info);
+		}
+	}
+	
+	SetupDiDestroyDeviceInfoList(deviceInfoSet);
+	return devices;
+}

package/native/usb_listener.h

@@ -0,0 +1,113 @@
+#ifndef USB_LISTENER_H
+#define USB_LISTENER_H
+
+#include <napi.h>
+#include <windows.h>
+#include <initguid.h>
+#include <setupapi.h>
+#include <cfgmgr32.h>
+#include <dbt.h>
+#include <string>
+#include <vector>
+#include <unordered_map>
+#include <memory>
+#include <atomic>
+#include <shared_mutex>
+
+/**
+ * Device information structure
+ * Contains all relevant USB device identification and location data
+ */
+struct DeviceInfo {
+	std::string deviceId;       // Windows device instance ID
+	uint16_t vid{0};            // Vendor ID
+	uint16_t pid{0};            // Product ID
+	std::string locationInfo;   // Physical port location
+	int logicalPort{-1};        // User-defined logical port number (-1 if not mapped)
+};
+
+/**
+ * RAII wrapper for Windows thread handle
+ */
+class ThreadHandle {
+public:
+	ThreadHandle() noexcept = default;
+	explicit ThreadHandle(HANDLE h) noexcept : handle(h) {}
+	~ThreadHandle() { if (handle) { WaitForSingleObject(handle, 5000); CloseHandle(handle); } }
+	
+	ThreadHandle(const ThreadHandle&) = delete;
+	ThreadHandle& operator=(const ThreadHandle&) = delete;
+	ThreadHandle(ThreadHandle&& other) noexcept : handle(std::exchange(other.handle, nullptr)) {}
+	ThreadHandle& operator=(ThreadHandle&& other) noexcept {
+		if (this != &other) {
+			if (handle) { WaitForSingleObject(handle, 5000); CloseHandle(handle); }
+			handle = std::exchange(other.handle, nullptr);
+		}
+		return *this;
+	}
+	
+	HANDLE get() const noexcept { return handle; }
+	explicit operator bool() const noexcept { return handle != nullptr; }
+	
+private:
+	HANDLE handle{nullptr};
+};
+
+/**
+ * USB Device Listener - Windows native implementation
+ * 
+ * Monitors USB device connection/disconnection events using Windows WM_DEVICECHANGE messages.
+ * Runs a hidden message-only window in a separate thread to receive device notifications.
+ * Thread-safe: callbacks are invoked on the Node.js thread using Napi::ThreadSafeFunction.
+ */
+class USBListener {
+public:
+	USBListener();
+	~USBListener();
+	
+	// Start monitoring USB device events
+	bool StartListening(std::string& errorMsg);
+	
+	// Stop monitoring and clean up resources
+	void StopListening();
+	
+	// Set callback for device connection events
+	void SetAddCallback(Napi::ThreadSafeFunction callback);
+	
+	// Set callback for device disconnection events
+	void SetRemoveCallback(Napi::ThreadSafeFunction callback);
+	
+	// Get list of all currently connected USB devices
+	std::vector<DeviceInfo> ListAllDevices();
+	
+private:
+	// Windows message handling
+	static LRESULT CALLBACK WindowProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam);
+	static DWORD WINAPI ListenerThreadProc(LPVOID param);
+	
+	// Core functionality
+	void MessageLoop();                                                         // Main message loop in listener thread
+	void HandleDeviceChange(WPARAM wParam, LPARAM lParam);                     // Process WM_DEVICECHANGE messages
+	bool GetDeviceInfo(const std::string& devicePath, DeviceInfo& info);       // Get device info from Windows API (for connections)
+	bool GetDeviceInfoFromPath(const std::string& devicePath, DeviceInfo& info); // Parse device info from path (for disconnections)
+	bool GetLocationInfo(DEVINST devInst, std::string& locationInfo);          // Get physical port location
+	bool GetVidPid(const std::string& deviceId, uint16_t& vid, uint16_t& pid); // Parse VID/PID from device ID string
+	void EnumerateConnectedDevices();                                          // Enumerate devices on startup
+	
+	// Windows handles (managed resources)
+	HWND m_hwnd{nullptr};                           // Hidden message-only window
+	HDEVNOTIFY m_notifyHandle{nullptr};             // Device notification handle
+	ThreadHandle m_thread;                          // Listener thread handle (RAII)
+	std::atomic<bool> m_running{false};             // Thread control flag
+	
+	// Device cache with shared_mutex for reader-writer lock pattern
+	// Multiple readers (enumerate) or single writer (add/remove)
+	mutable std::shared_mutex m_cacheMutex;         // C++17 shared_mutex for better concurrency
+	std::unordered_map<std::string, DeviceInfo> m_deviceCache;  // Fast lookup with hash
+	
+	// Callbacks
+	Napi::ThreadSafeFunction m_addCallback;         // Device add callback
+	Napi::ThreadSafeFunction m_removeCallback;      // Device remove callback
+};
+
+#endif // USB_LISTENER_H

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@mcesystems/usb-device-listener",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Native Windows USB device listener using PnP notifications without custom drivers",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/types.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/types.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/types.d.ts"
+      "require": "./dist/index.cjs"
     }
   },
   "keywords": [
@@ -52,14 +53,16 @@
     "dist",
     "prebuilds",
     "build/Release/*.node",
-    "README.md"
+    "README.md",
+    "native",
+    "binding.gyp"
   ],
   "gypfile": true,
   "os": [
     "win32"
   ],
   "scripts": {
-    "prebuild:gyp": "prebuildify --napi --strip --target 25.2.1",
+    "prebuild:gyp": "prebuildify --napi --electron --strip --target 25.2.1",
     "build": "tsx esbuild.config.ts && tsc --emitDeclarationOnly",
     "rebuild": "node-gyp rebuild",
     "install": "node-gyp-build",