@mcesystems/usb-device-listener 1.0.0

package/README.md

@@ -0,0 +1,323 @@
+# USB Device Listener
+
+A high-performance native Node.js addon for monitoring USB device connections and disconnections on Windows. Built with N-API for stability across Node.js versions.
+
+## Features
+
+- ⚡ **Real-time monitoring** - Immediate notification of USB device events via native Windows API
+- 🎯 **Device filtering** - Monitor specific devices by VID/PID or hub location
+- 📍 **Physical port mapping** - Map USB ports to logical port numbers for consistent device identification
+- 🧵 **Thread-safe** - Runs in separate thread without blocking Node.js event loop
+- 💪 **Production-ready** - Memory-safe, handles multiple simultaneous device changes
+- 🔍 **Device enumeration** - List all currently connected devices
+
+## Installation
+
+```bash
+npm install
+```
+
+### Requirements
+
+- **Node.js**: v18+ (ESM support required)
+- **Windows**: 10/11 (uses Windows Device Management API)
+- **Build tools**: Visual Studio 2022 with C++ build tools
+
+## Quick Start
+
+```javascript
+import usbListener from 'usb-device-listener';
+
+// Define configuration
+const config = {
+	logicalPortMap: {
+		"Port_#0005.Hub_#0002": 1,  // Map physical port to logical port 1
+		"Port_#0006.Hub_#0002": 2
+	},
+	targetDevices: [
+		{ vid: "04E8", pid: "6860" }  // Only monitor Samsung devices
+	],
+	ignoredHubs: [],
+	listenOnlyHubs: []
+};
+
+// Register event handlers
+usbListener.onDeviceAdd((device) => {
+	console.log('Device connected:', device.locationInfo);
+	console.log('VID:PID:', `${device.vid.toString(16)}:${device.pid.toString(16)}`);
+	console.log('Logical Port:', device.logicalPort);
+});
+
+usbListener.onDeviceRemove((device) => {
+	console.log('Device disconnected:', device.locationInfo);
+});
+
+// Start listening
+try {
+	usbListener.startListening(config);
+	console.log('Listening for USB events...');
+} catch (error) {
+	console.error('Failed to start:', error.message);
+}
+
+// Graceful shutdown
+process.on('SIGINT', () => {
+	usbListener.stopListening();
+	process.exit(0);
+});
+```
+
+## API Reference
+
+### `startListening(config)`
+
+Start monitoring USB device events.
+
+**Parameters:**
+- `config` (Object): Configuration object
+  - `logicalPortMap` (Object, optional): Map physical locations to logical port numbers
+    - Key: Location string (e.g., "Port_#0005.Hub_#0002")
+    - Value: Logical port number (integer)
+  - `targetDevices` (Array, optional): Filter specific devices by VID/PID
+    - Each element: `{ vid: string, pid: string }` (hex strings, e.g., "04E8")
+    - Empty array = monitor all devices
+  - `ignoredHubs` (Array, optional): Hub location strings to ignore
+  - `listenOnlyHubs` (Array, optional): Only monitor these hub locations
+
+**Throws:**
+- `TypeError` if config is not an object
+- `Error` if listener is already running
+
+**Example:**
+```javascript
+usbListener.startListening({
+	logicalPortMap: {
+		"Port_#0005.Hub_#0002": 1
+	},
+	targetDevices: [],  // Monitor all devices
+	ignoredHubs: ["Port_#0001.Hub_#0001"],  // Ignore this hub
+	listenOnlyHubs: []  // No restriction
+});
+```
+
+### `stopListening()`
+
+Stop monitoring and clean up resources. Safe to call multiple times.
+
+**Example:**
+```javascript
+usbListener.stopListening();
+```
+
+### `onDeviceAdd(callback)`
+
+Register callback for device connection events.
+
+**Parameters:**
+- `callback` (Function): Called when device is connected
+  - `deviceInfo` (Object):
+    - `deviceId` (string): Windows device instance ID
+    - `vid` (number): Vendor ID (decimal)
+    - `pid` (number): Product ID (decimal)
+    - `locationInfo` (string): Physical port location
+    - `logicalPort` (number|null): Mapped logical port or null
+
+**Example:**
+```javascript
+usbListener.onDeviceAdd((device) => {
+	const vidHex = device.vid.toString(16).toUpperCase().padStart(4, '0');
+	const pidHex = device.pid.toString(16).toUpperCase().padStart(4, '0');
+	console.log(`Device ${vidHex}:${pidHex} on port ${device.logicalPort || 'unmapped'}`);
+});
+```
+
+### `onDeviceRemove(callback)`
+
+Register callback for device disconnection events. Device info format same as `onDeviceAdd`.
+
+**Example:**
+```javascript
+usbListener.onDeviceRemove((device) => {
+	console.log(`Port ${device.logicalPort} disconnected`);
+});
+```
+
+### `listDevices()`
+
+Get list of all currently connected USB devices.
+
+**Returns:** Array of device objects (same format as callback parameter)
+
+**Example:**
+```javascript
+const devices = usbListener.listDevices();
+devices.forEach(device => {
+	console.log(`${device.locationInfo}: VID=${device.vid.toString(16)}`);
+});
+```
+
+## How It Works
+
+### Physical Port Location
+
+Windows assigns a unique location string to each USB port:
+- Format: `Port_#XXXX.Hub_#YYYY`
+- Example: `Port_#0005.Hub_#0002`
+- **Stable**: Same port always has same location string
+- **Use case**: Map to logical port numbers (1, 2, 3...) for your application
+
+### Getting Location Strings
+
+Use the included `list-devices.js` utility:
+
+```bash
+node list-devices.js
+```
+
+Output:
+```
+Device 1:
+  Device ID: USB\VID_04E8&PID_6860\R58NC2971AJ
+  VID: 0x04E8
+  PID: 0x6860
+  Location Info (mapping key): Port_#0005.Hub_#0002
+
+Device 2:
+  Device ID: USB\VID_27C6&PID_6594\UID0014C59F
+  VID: 0x27C6
+  PID: 0x6594
+  Location Info (mapping key): Port_#0007.Hub_#0002
+```
+
+Copy the "Location Info" values to use in your `logicalPortMap`.
+
+### Device Filtering
+
+**By VID/PID:**
+```javascript
+targetDevices: [
+	{ vid: "2341", pid: "0043" },  // Arduino Uno
+	{ vid: "0483", pid: "5740" }   // STM32
+]
+```
+
+**By Hub:**
+```javascript
+listenOnlyHubs: ["Hub_#0002"]  // Only monitor this hub
+// or
+ignoredHubs: ["Hub_#0001"]     // Ignore this hub
+```
+
+## Performance & Scalability
+
+### Handling Many Devices
+
+The listener is designed to handle multiple simultaneous device events efficiently:
+
+✅ **Thread-safe**: Device cache protected by mutex  
+✅ **Non-blocking**: Runs in separate thread, doesn't block Node.js  
+✅ **Efficient**: Only processes filtered devices  
+✅ **Memory-safe**: Automatic cleanup on disconnect  
+
+### Tested Scenarios
+
+- Multiple rapid connect/disconnect cycles
+- Simultaneous connection of 10+ devices
+- Hub with many devices
+- Long-running processes (hours/days)
+
+### Best Practices
+
+1. **Use device filtering** when possible to reduce CPU usage:
+   ```javascript
+   targetDevices: [{ vid: "04E8", pid: "6860" }]  // Better than monitoring all
+   ```
+
+2. **Keep callbacks fast** - offload heavy processing:
+   ```javascript
+   onDeviceAdd((device) => {
+   	// Good: Quick database write
+   	db.logConnection(device);
+   	
+   	// Bad: Long synchronous operation
+   	// processLargeFile(device);  // Use setTimeout or worker thread instead
+   });
+   ```
+
+3. **Handle errors gracefully**:
+   ```javascript
+   onDeviceAdd((device) => {
+   	try {
+   		processDevice(device);
+   	} catch (error) {
+   		console.error('Device processing failed:', error);
+   	}
+   });
+   ```
+
+4. **Clean shutdown**:
+   ```javascript
+   process.on('SIGINT', () => {
+   	usbListener.stopListening();
+   	// Wait briefly for cleanup
+   	setTimeout(() => process.exit(0), 100);
+   });
+   ```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│          Node.js Application            │
+│  ┌─────────────────────────────────┐   │
+│  │      JavaScript API             │   │
+│  │   (index.js - documented)       │   │
+│  └────────────┬────────────────────┘   │
+│               │                         │
+│  ┌────────────▼────────────────────┐   │
+│  │    N-API Addon (addon.cc)       │   │
+│  │  - Converts JS ↔ C++ types      │   │
+│  │  - ThreadSafeFunction callbacks │   │
+│  └────────────┬────────────────────┘   │
+└───────────────┼─────────────────────────┘
+                │
+┌───────────────▼─────────────────────────┐
+│      USBListener (usb_listener.cc)      │
+│  ┌───────────────────────────────────┐ │
+│  │  Listener Thread (MessageLoop)    │ │
+│  │  - Hidden message-only window     │ │
+│  │  - RegisterDeviceNotification     │ │
+│  │  - Receives WM_DEVICECHANGE       │ │
+│  └──────────┬────────────────────────┘ │
+│             │                           │
+│  ┌──────────▼──────────────────────┐   │
+│  │  Windows Device Management API   │   │
+│  │  - SetupDi* functions            │   │
+│  │  - CM_Get_DevNode_*              │   │
+│  └──────────────────────────────────┘   │
+└─────────────────────────────────────────┘
+```
+
+## Troubleshooting
+
+**Build errors:**
+- Ensure Visual Studio C++ build tools are installed
+- Run from "x64 Native Tools Command Prompt"
+
+**No events firing:**
+- Check `targetDevices` filter isn't too restrictive
+- Verify callbacks are registered before calling `startListening()`
+- Use `listDevices()` to confirm devices are visible
+
+**Incorrect location info:**
+- Location strings are generated by Windows
+- Different USB controllers may use different formats
+- Always use `listDevices()` to get actual location strings
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and pull requests welcome!

package/device-filter.d.ts

@@ -0,0 +1,24 @@
+import type { DeviceInfo, ListenerConfig } from "./types";
+/**
+ * Determine if a device notification should be sent based on the configuration.
+ *
+ * Filter priority (highest to lowest):
+ * 1. ignoredDevices - if device matches, always return false
+ * 2. listenOnlyDevices - if specified, device must match at least one
+ * 3. targetDevices - if specified, device must match at least one
+ * 4. logicalPortMap - if specified, device location must be in the map
+ *
+ * @param device - The device information from the native addon
+ * @param config - The listener configuration
+ * @returns true if the device should trigger a notification, false otherwise
+ */
+export declare function shouldNotifyDevice(device: DeviceInfo, config: ListenerConfig): boolean;
+/**
+ * Apply logical port mapping to a device if configured
+ *
+ * @param device - The device information from the native addon
+ * @param config - The listener configuration
+ * @returns Device info with logicalPort set if mapped, otherwise unchanged
+ */
+export declare function applyLogicalPortMapping(device: DeviceInfo, config: ListenerConfig): DeviceInfo;
+//# sourceMappingURL=device-filter.d.ts.map

package/device-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-filter.d.ts","sourceRoot":"","sources":["../src/device-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAgB,MAAM,SAAS,CAAC;AA4BxE;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CA8BtF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,UAAU,CAQ9F"}

package/examples/example.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=example.d.ts.map

package/examples/example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../src/examples/example.ts"],"names":[],"mappings":""}

package/examples/example.js

@@ -0,0 +1,187 @@
+// src/index.ts
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "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, config2) {
+  if (config2.ignoredDevices && config2.ignoredDevices.length > 0) {
+    if (matchesAnyDevice(device, config2.ignoredDevices)) {
+      return false;
+    }
+  }
+  if (config2.listenOnlyDevices && config2.listenOnlyDevices.length > 0) {
+    if (!matchesAnyDevice(device, config2.listenOnlyDevices)) {
+      return false;
+    }
+  }
+  if (config2.targetDevices && config2.targetDevices.length > 0) {
+    if (!matchesAnyDevice(device, config2.targetDevices)) {
+      return false;
+    }
+  }
+  if (config2.logicalPortMap && Object.keys(config2.logicalPortMap).length > 0) {
+    if (!(device.locationInfo in config2.logicalPortMap)) {
+      return false;
+    }
+  }
+  return true;
+}
+function applyLogicalPortMapping(device, config2) {
+  if (config2.logicalPortMap && device.locationInfo in config2.logicalPortMap) {
+    return {
+      ...device,
+      logicalPort: config2.logicalPortMap[device.locationInfo]
+    };
+  }
+  return device;
+}
+
+// src/index.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var packageRoot = dirname(__dirname);
+function loadNativeAddon() {
+  const require2 = createRequire(import.meta.url);
+  const addonPath = join(packageRoot, "build", "Release", "@mcesystems+usb-device-listener.node");
+  try {
+    return require2(addonPath);
+  } catch {
+    try {
+      const nodeGypBuild = require2("node-gyp-build");
+      return nodeGypBuild(packageRoot);
+    } catch {
+      throw new Error(
+        `Failed to load native addon. Tried:
+  1. Direct path: ${addonPath}
+  2. node-gyp-build search
+Make sure the addon is built with 'npm run rebuild' or 'npm run prebuild'`
+      );
+    }
+  }
+}
+var addon = loadNativeAddon();
+var UsbDeviceListenerImpl = class {
+  config = {};
+  userAddCallback = null;
+  userRemoveCallback = null;
+  /**
+   * Start listening for USB device events
+   */
+  startListening(config2) {
+    if (typeof config2 !== "object" || config2 === null) {
+      throw new TypeError("Config must be an object");
+    }
+    this.config = config2;
+    addon.startListening();
+  }
+  /**
+   * Stop listening for USB device events
+   */
+  stopListening() {
+    addon.stopListening();
+  }
+  /**
+   * Register callback for device connection events
+   */
+  onDeviceAdd(callback) {
+    if (typeof callback !== "function") {
+      throw new TypeError("Callback must be a function");
+    }
+    this.userAddCallback = callback;
+    addon.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;
+    addon.onDeviceRemove((device) => {
+      if (shouldNotifyDevice(device, this.config)) {
+        const enrichedDevice = applyLogicalPortMapping(device, this.config);
+        this.userRemoveCallback?.(enrichedDevice);
+      }
+    });
+  }
+  /**
+   * List all currently connected USB devices
+   */
+  listDevices() {
+    return addon.listDevices();
+  }
+};
+var usbDeviceListener = new UsbDeviceListenerImpl();
+var index_default = usbDeviceListener;
+
+// src/examples/example.ts
+var config = {
+  logicalPortMap: {
+    "Port_#0005.Hub_#0002": 1,
+    "Port_#0006.Hub_#0002": 2
+  },
+  ignoredDevices: [],
+  listenOnlyDevices: []
+};
+index_default.onDeviceAdd((device) => {
+  console.log("Device connected:");
+  console.log("  Device ID:", device.deviceId);
+  console.log(`  VID: 0x${device.vid.toString(16).toUpperCase().padStart(4, "0")}`);
+  console.log(`  PID: 0x${device.pid.toString(16).toUpperCase().padStart(4, "0")}`);
+  console.log("  Location:", device.locationInfo);
+  console.log("  Logical Port:", device.logicalPort !== null ? device.logicalPort : "Not mapped");
+  console.log("");
+});
+index_default.onDeviceRemove((device) => {
+  console.log("Device disconnected:");
+  console.log("  Device ID:", device.deviceId);
+  console.log(`  VID: 0x${device.vid.toString(16).toUpperCase().padStart(4, "0")}`);
+  console.log(`  PID: 0x${device.pid.toString(16).toUpperCase().padStart(4, "0")}`);
+  console.log("  Location:", device.locationInfo);
+  console.log("  Logical Port:", device.logicalPort !== null ? device.logicalPort : "Not mapped");
+  console.log("");
+});
+try {
+  console.log("Starting USB device listener...");
+  console.log("Config:", JSON.stringify(config, null, 2));
+  console.log("");
+  index_default.startListening(config);
+  console.log("Listening for USB device events. Press Ctrl+C to stop.");
+  console.log("");
+} catch (error) {
+  if (error instanceof Error) {
+    console.error("Error starting listener:", error.message);
+  }
+  process.exit(1);
+}
+process.on("SIGINT", () => {
+  console.log("\nStopping listener...");
+  index_default.stopListening();
+  process.exit(0);
+});
+process.on("SIGTERM", () => {
+  console.log("\nStopping listener...");
+  index_default.stopListening();
+  process.exit(0);
+});
+//# sourceMappingURL=example.js.map

package/examples/example.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/index.ts", "../../src/device-filter.ts", "../../src/examples/example.ts"],
+  "sourcesContent": ["\nimport { createRequire } from \"node:module\";\nimport { dirname, join } 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\tUsbDeviceListener,\n} from \"./types\";\n\n/**\n * Native addon interface\n * This is the raw C++ addon loaded via N-API\n */\ninterface NativeAddon {\n\tstartListening(): void;\n\tstopListening(): void;\n\tonDeviceAdd(callback: DeviceAddCallback): void;\n\tonDeviceRemove(callback: DeviceRemoveCallback): void;\n\tlistDevices(): DeviceInfo[];\n}\n\n// ESM compatibility: get __dirname equivalent\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\nconst packageRoot = dirname(__dirname);\n\n/**\n * Load native addon\n * In development: uses node-gyp-build to find the addon\n * In production: loads directly from the known build location\n */\nfunction loadNativeAddon(): NativeAddon {\n\tconst require = createRequire(import.meta.url);\n\n\t// Try to load from the known production location first\n\tconst addonPath = join(packageRoot, \"build\", \"Release\", \"@mcesystems+usb-device-listener.node\");\n\n\ttry {\n\t\treturn require(addonPath);\n\t} catch {\n\t\t// Fallback to node-gyp-build for development (if available)\n\t\ttry {\n\t\t\tconst nodeGypBuild = require(\"node-gyp-build\");\n\t\t\treturn nodeGypBuild(packageRoot);\n\t\t} catch {\n\t\t\tthrow new Error(\n\t\t\t\t`Failed to load native addon. Tried:\\n  1. Direct path: ${addonPath}\\n  2. node-gyp-build search\\nMake sure the addon is built with 'npm run rebuild' or 'npm run prebuild'`\n\t\t\t);\n\t\t}\n\t}\n}\n\nconst addon = loadNativeAddon();\n\n/**\n * USB Device Listener implementation\n * Provides a type-safe wrapper around the native C++ addon\n */\nclass UsbDeviceListenerImpl implements UsbDeviceListener {\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\taddon.startListening();\n\t}\n\n\t/**\n\t * Stop listening for USB device events\n\t */\n\tpublic stopListening(): void {\n\t\taddon.stopListening();\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\taddon.onDeviceAdd((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\taddon.onDeviceRemove((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 addon.listDevices();\n\t}\n}\n\n// Export singleton instance\nconst usbDeviceListener: UsbDeviceListener = new UsbDeviceListenerImpl();\n\nexport default usbDeviceListener;\nexport type {\n\tDeviceInfo,\n\tDeviceAddCallback,\n\tDeviceRemoveCallback,\n\tListenerConfig,\n\tTargetDevice,\n\tUsbDeviceListener,\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", "import usbListener, { type DeviceInfo, type ListenerConfig } from \"../index\";\n\n// Type-safe configuration - no casting needed!\nconst config: ListenerConfig = {\n\tlogicalPortMap: {\n\t\t\"Port_#0005.Hub_#0002\": 1,\n\t\t\"Port_#0006.Hub_#0002\": 2,\n\t},\n\tignoredDevices: [],\n\tlistenOnlyDevices: [],\n};\n\n// Type-safe callback with full IntelliSense\nusbListener.onDeviceAdd((device: DeviceInfo) => {\n\tconsole.log(\"Device connected:\");\n\tconsole.log(\"  Device ID:\", device.deviceId);\n\tconsole.log(`  VID: 0x${device.vid.toString(16).toUpperCase().padStart(4, \"0\")}`);\n\tconsole.log(`  PID: 0x${device.pid.toString(16).toUpperCase().padStart(4, \"0\")}`);\n\tconsole.log(\"  Location:\", device.locationInfo);\n\tconsole.log(\"  Logical Port:\", device.logicalPort !== null ? device.logicalPort : \"Not mapped\");\n\tconsole.log(\"\");\n});\n\nusbListener.onDeviceRemove((device: DeviceInfo) => {\n\tconsole.log(\"Device disconnected:\");\n\tconsole.log(\"  Device ID:\", device.deviceId);\n\tconsole.log(`  VID: 0x${device.vid.toString(16).toUpperCase().padStart(4, \"0\")}`);\n\tconsole.log(`  PID: 0x${device.pid.toString(16).toUpperCase().padStart(4, \"0\")}`);\n\tconsole.log(\"  Location:\", device.locationInfo);\n\tconsole.log(\"  Logical Port:\", device.logicalPort !== null ? device.logicalPort : \"Not mapped\");\n\tconsole.log(\"\");\n});\n\ntry {\n\tconsole.log(\"Starting USB device listener...\");\n\tconsole.log(\"Config:\", JSON.stringify(config, null, 2));\n\tconsole.log(\"\");\n\n\tusbListener.startListening(config);\n\n\tconsole.log(\"Listening for USB device events. Press Ctrl+C to stop.\");\n\tconsole.log(\"\");\n} catch (error) {\n\tif (error instanceof Error) {\n\t\tconsole.error(\"Error starting listener:\", error.message);\n\t}\n\tprocess.exit(1);\n}\n\nprocess.on(\"SIGINT\", () => {\n\tconsole.log(\"\\nStopping listener...\");\n\tusbListener.stopListening();\n\tprocess.exit(0);\n});\n\nprocess.on(\"SIGTERM\", () => {\n\tconsole.log(\"\\nStopping listener...\");\n\tusbListener.stopListening();\n\tprocess.exit(0);\n});\n"],
+  "mappings": "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",
+  "names": ["config", "require", "config"]
+}

package/examples/list-devices.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=list-devices.d.ts.map

package/examples/list-devices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-devices.d.ts","sourceRoot":"","sources":["../../src/examples/list-devices.ts"],"names":[],"mappings":""}

package/examples/list-devices.js

@@ -0,0 +1,162 @@
+// src/index.ts
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "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 = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var packageRoot = dirname(__dirname);
+function loadNativeAddon() {
+  const require2 = createRequire(import.meta.url);
+  const addonPath = join(packageRoot, "build", "Release", "@mcesystems+usb-device-listener.node");
+  try {
+    return require2(addonPath);
+  } catch {
+    try {
+      const nodeGypBuild = require2("node-gyp-build");
+      return nodeGypBuild(packageRoot);
+    } catch {
+      throw new Error(
+        `Failed to load native addon. Tried:
+  1. Direct path: ${addonPath}
+  2. node-gyp-build search
+Make sure the addon is built with 'npm run rebuild' or 'npm run prebuild'`
+      );
+    }
+  }
+}
+var addon = loadNativeAddon();
+var UsbDeviceListenerImpl = 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;
+    addon.startListening();
+  }
+  /**
+   * Stop listening for USB device events
+   */
+  stopListening() {
+    addon.stopListening();
+  }
+  /**
+   * Register callback for device connection events
+   */
+  onDeviceAdd(callback) {
+    if (typeof callback !== "function") {
+      throw new TypeError("Callback must be a function");
+    }
+    this.userAddCallback = callback;
+    addon.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;
+    addon.onDeviceRemove((device) => {
+      if (shouldNotifyDevice(device, this.config)) {
+        const enrichedDevice = applyLogicalPortMapping(device, this.config);
+        this.userRemoveCallback?.(enrichedDevice);
+      }
+    });
+  }
+  /**
+   * List all currently connected USB devices
+   */
+  listDevices() {
+    return addon.listDevices();
+  }
+};
+var usbDeviceListener = new UsbDeviceListenerImpl();
+var index_default = usbDeviceListener;
+
+// src/examples/list-devices.ts
+console.log("Listing all connected USB devices:\n");
+try {
+  const devices = index_default.listDevices();
+  if (devices.length === 0) {
+    console.log("No USB devices found.");
+  } else {
+    devices.forEach((device, index) => {
+      console.log(`Device ${index + 1}:`);
+      console.log(`  Device ID: ${device.deviceId}`);
+      console.log(`  VID: 0x${device.vid.toString(16).toUpperCase().padStart(4, "0")}`);
+      console.log(`  PID: 0x${device.pid.toString(16).toUpperCase().padStart(4, "0")}`);
+      console.log(`  Location Info (mapping key): ${device.locationInfo}`);
+      console.log("");
+    });
+    console.log(`Total devices: ${devices.length}`);
+    console.log(
+      '\nTo add a device to your config, use the "Location Info" as the key in the logicalPortMap.'
+    );
+  }
+} catch (error) {
+  if (error instanceof Error) {
+    console.error("Error listing devices:", error.message);
+  }
+}
+//# sourceMappingURL=list-devices.js.map

package/examples/list-devices.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/index.ts", "../../src/device-filter.ts", "../../src/examples/list-devices.ts"],
+  "sourcesContent": ["\nimport { createRequire } from \"node:module\";\nimport { dirname, join } 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\tUsbDeviceListener,\n} from \"./types\";\n\n/**\n * Native addon interface\n * This is the raw C++ addon loaded via N-API\n */\ninterface NativeAddon {\n\tstartListening(): void;\n\tstopListening(): void;\n\tonDeviceAdd(callback: DeviceAddCallback): void;\n\tonDeviceRemove(callback: DeviceRemoveCallback): void;\n\tlistDevices(): DeviceInfo[];\n}\n\n// ESM compatibility: get __dirname equivalent\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\nconst packageRoot = dirname(__dirname);\n\n/**\n * Load native addon\n * In development: uses node-gyp-build to find the addon\n * In production: loads directly from the known build location\n */\nfunction loadNativeAddon(): NativeAddon {\n\tconst require = createRequire(import.meta.url);\n\n\t// Try to load from the known production location first\n\tconst addonPath = join(packageRoot, \"build\", \"Release\", \"@mcesystems+usb-device-listener.node\");\n\n\ttry {\n\t\treturn require(addonPath);\n\t} catch {\n\t\t// Fallback to node-gyp-build for development (if available)\n\t\ttry {\n\t\t\tconst nodeGypBuild = require(\"node-gyp-build\");\n\t\t\treturn nodeGypBuild(packageRoot);\n\t\t} catch {\n\t\t\tthrow new Error(\n\t\t\t\t`Failed to load native addon. Tried:\\n  1. Direct path: ${addonPath}\\n  2. node-gyp-build search\\nMake sure the addon is built with 'npm run rebuild' or 'npm run prebuild'`\n\t\t\t);\n\t\t}\n\t}\n}\n\nconst addon = loadNativeAddon();\n\n/**\n * USB Device Listener implementation\n * Provides a type-safe wrapper around the native C++ addon\n */\nclass UsbDeviceListenerImpl implements UsbDeviceListener {\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\taddon.startListening();\n\t}\n\n\t/**\n\t * Stop listening for USB device events\n\t */\n\tpublic stopListening(): void {\n\t\taddon.stopListening();\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\taddon.onDeviceAdd((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\taddon.onDeviceRemove((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 addon.listDevices();\n\t}\n}\n\n// Export singleton instance\nconst usbDeviceListener: UsbDeviceListener = new UsbDeviceListenerImpl();\n\nexport default usbDeviceListener;\nexport type {\n\tDeviceInfo,\n\tDeviceAddCallback,\n\tDeviceRemoveCallback,\n\tListenerConfig,\n\tTargetDevice,\n\tUsbDeviceListener,\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", "import usbListener, { type DeviceInfo } from \"../index\";\n\nconsole.log(\"Listing all connected USB devices:\\n\");\n\ntry {\n\tconst devices: DeviceInfo[] = usbListener.listDevices();\n\n\tif (devices.length === 0) {\n\t\tconsole.log(\"No USB devices found.\");\n\t} else {\n\t\tdevices.forEach((device: DeviceInfo, index: number) => {\n\t\t\tconsole.log(`Device ${index + 1}:`);\n\t\t\tconsole.log(`  Device ID: ${device.deviceId}`);\n\t\t\tconsole.log(`  VID: 0x${device.vid.toString(16).toUpperCase().padStart(4, \"0\")}`);\n\t\t\tconsole.log(`  PID: 0x${device.pid.toString(16).toUpperCase().padStart(4, \"0\")}`);\n\t\t\tconsole.log(`  Location Info (mapping key): ${device.locationInfo}`);\n\t\t\tconsole.log(\"\");\n\t\t});\n\n\t\tconsole.log(`Total devices: ${devices.length}`);\n\t\tconsole.log(\n\t\t\t'\\nTo add a device to your config, use the \"Location Info\" as the key in the logicalPortMap.'\n\t\t);\n\t}\n} catch (error) {\n\tif (error instanceof Error) {\n\t\tconsole.error(\"Error listing devices:\", error.message);\n\t}\n}\n"],
+  "mappings": "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",
+  "names": ["require"]
+}

package/index.d.ts

@@ -0,0 +1,5 @@
+import type { UsbDeviceListener } from "./types";
+declare const usbDeviceListener: UsbDeviceListener;
+export default usbDeviceListener;
+export type { DeviceInfo, DeviceAddCallback, DeviceRemoveCallback, ListenerConfig, TargetDevice, UsbDeviceListener, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAKX,iBAAiB,EACjB,MAAM,SAAS,CAAC;AAwHjB,QAAA,MAAM,iBAAiB,EAAE,iBAA+C,CAAC;AAEzE,eAAe,iBAAiB,CAAC;AACjC,YAAY,EACX,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,YAAY,EACZ,iBAAiB,GACjB,MAAM,SAAS,CAAC"}

package/index.js

@@ -0,0 +1,139 @@
+// src/index.ts
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "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 = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var packageRoot = dirname(__dirname);
+function loadNativeAddon() {
+  const require2 = createRequire(import.meta.url);
+  const addonPath = join(packageRoot, "build", "Release", "@mcesystems+usb-device-listener.node");
+  try {
+    return require2(addonPath);
+  } catch {
+    try {
+      const nodeGypBuild = require2("node-gyp-build");
+      return nodeGypBuild(packageRoot);
+    } catch {
+      throw new Error(
+        `Failed to load native addon. Tried:
+  1. Direct path: ${addonPath}
+  2. node-gyp-build search
+Make sure the addon is built with 'npm run rebuild' or 'npm run prebuild'`
+      );
+    }
+  }
+}
+var addon = loadNativeAddon();
+var UsbDeviceListenerImpl = 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;
+    addon.startListening();
+  }
+  /**
+   * Stop listening for USB device events
+   */
+  stopListening() {
+    addon.stopListening();
+  }
+  /**
+   * Register callback for device connection events
+   */
+  onDeviceAdd(callback) {
+    if (typeof callback !== "function") {
+      throw new TypeError("Callback must be a function");
+    }
+    this.userAddCallback = callback;
+    addon.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;
+    addon.onDeviceRemove((device) => {
+      if (shouldNotifyDevice(device, this.config)) {
+        const enrichedDevice = applyLogicalPortMapping(device, this.config);
+        this.userRemoveCallback?.(enrichedDevice);
+      }
+    });
+  }
+  /**
+   * List all currently connected USB devices
+   */
+  listDevices() {
+    return addon.listDevices();
+  }
+};
+var usbDeviceListener = new UsbDeviceListenerImpl();
+var index_default = usbDeviceListener;
+export {
+  index_default as default
+};
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts", "../src/device-filter.ts"],
+  "sourcesContent": ["\nimport { createRequire } from \"node:module\";\nimport { dirname, join } 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\tUsbDeviceListener,\n} from \"./types\";\n\n/**\n * Native addon interface\n * This is the raw C++ addon loaded via N-API\n */\ninterface NativeAddon {\n\tstartListening(): void;\n\tstopListening(): void;\n\tonDeviceAdd(callback: DeviceAddCallback): void;\n\tonDeviceRemove(callback: DeviceRemoveCallback): void;\n\tlistDevices(): DeviceInfo[];\n}\n\n// ESM compatibility: get __dirname equivalent\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\nconst packageRoot = dirname(__dirname);\n\n/**\n * Load native addon\n * In development: uses node-gyp-build to find the addon\n * In production: loads directly from the known build location\n */\nfunction loadNativeAddon(): NativeAddon {\n\tconst require = createRequire(import.meta.url);\n\n\t// Try to load from the known production location first\n\tconst addonPath = join(packageRoot, \"build\", \"Release\", \"@mcesystems+usb-device-listener.node\");\n\n\ttry {\n\t\treturn require(addonPath);\n\t} catch {\n\t\t// Fallback to node-gyp-build for development (if available)\n\t\ttry {\n\t\t\tconst nodeGypBuild = require(\"node-gyp-build\");\n\t\t\treturn nodeGypBuild(packageRoot);\n\t\t} catch {\n\t\t\tthrow new Error(\n\t\t\t\t`Failed to load native addon. Tried:\\n  1. Direct path: ${addonPath}\\n  2. node-gyp-build search\\nMake sure the addon is built with 'npm run rebuild' or 'npm run prebuild'`\n\t\t\t);\n\t\t}\n\t}\n}\n\nconst addon = loadNativeAddon();\n\n/**\n * USB Device Listener implementation\n * Provides a type-safe wrapper around the native C++ addon\n */\nclass UsbDeviceListenerImpl implements UsbDeviceListener {\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\taddon.startListening();\n\t}\n\n\t/**\n\t * Stop listening for USB device events\n\t */\n\tpublic stopListening(): void {\n\t\taddon.stopListening();\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\taddon.onDeviceAdd((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\taddon.onDeviceRemove((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 addon.listDevices();\n\t}\n}\n\n// Export singleton instance\nconst usbDeviceListener: UsbDeviceListener = new UsbDeviceListenerImpl();\n\nexport default usbDeviceListener;\nexport type {\n\tDeviceInfo,\n\tDeviceAddCallback,\n\tDeviceRemoveCallback,\n\tListenerConfig,\n\tTargetDevice,\n\tUsbDeviceListener,\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": ";AACA,SAAS,qBAAqB;AAC9B,SAAS,SAAS,YAAY;AAC9B,SAAS,qBAAqB;;;ACE9B,SAAS,YAAY,OAAuB;AAC3C,SAAO,MAAM,SAAS,EAAE,EAAE,YAAY,EAAE,SAAS,GAAG,GAAG;AACxD;AAKA,SAAS,cAAc,QAAoB,QAA+B;AACzE,QAAM,YAAY,YAAY,OAAO,GAAG;AACxC,QAAM,YAAY,YAAY,OAAO,GAAG;AACxC,QAAM,YAAY,OAAO,IAAI,YAAY;AACzC,QAAM,YAAY,OAAO,IAAI,YAAY;AAEzC,SAAO,cAAc,aAAa,cAAc;AACjD;AAKA,SAAS,iBAAiB,QAAoB,SAAkC;AAC/E,SAAO,QAAQ,KAAK,CAAC,WAAW,cAAc,QAAQ,MAAM,CAAC;AAC9D;AAeO,SAAS,mBAAmB,QAAoB,QAAiC;AAEvF,MAAI,OAAO,kBAAkB,OAAO,eAAe,SAAS,GAAG;AAC9D,QAAI,iBAAiB,QAAQ,OAAO,cAAc,GAAG;AACpD,aAAO;AAAA,IACR;AAAA,EACD;AAGA,MAAI,OAAO,qBAAqB,OAAO,kBAAkB,SAAS,GAAG;AACpE,QAAI,CAAC,iBAAiB,QAAQ,OAAO,iBAAiB,GAAG;AACxD,aAAO;AAAA,IACR;AAAA,EACD;AAGA,MAAI,OAAO,iBAAiB,OAAO,cAAc,SAAS,GAAG;AAC5D,QAAI,CAAC,iBAAiB,QAAQ,OAAO,aAAa,GAAG;AACpD,aAAO;AAAA,IACR;AAAA,EACD;AAGA,MAAI,OAAO,kBAAkB,OAAO,KAAK,OAAO,cAAc,EAAE,SAAS,GAAG;AAC3E,QAAI,EAAE,OAAO,gBAAgB,OAAO,iBAAiB;AACpD,aAAO;AAAA,IACR;AAAA,EACD;AAEA,SAAO;AACR;AASO,SAAS,wBAAwB,QAAoB,QAAoC;AAC/F,MAAI,OAAO,kBAAkB,OAAO,gBAAgB,OAAO,gBAAgB;AAC1E,WAAO;AAAA,MACN,GAAG;AAAA,MACH,aAAa,OAAO,eAAe,OAAO,YAAY;AAAA,IACvD;AAAA,EACD;AACA,SAAO;AACR;;;AD9DA,IAAM,aAAa,cAAc,YAAY,GAAG;AAChD,IAAM,YAAY,QAAQ,UAAU;AAEpC,IAAM,cAAc,QAAQ,SAAS;AAOrC,SAAS,kBAA+B;AACvC,QAAMA,WAAU,cAAc,YAAY,GAAG;AAG7C,QAAM,YAAY,KAAK,aAAa,SAAS,WAAW,sCAAsC;AAE9F,MAAI;AACH,WAAOA,SAAQ,SAAS;AAAA,EACzB,QAAQ;AAEP,QAAI;AACH,YAAM,eAAeA,SAAQ,gBAAgB;AAC7C,aAAO,aAAa,WAAW;AAAA,IAChC,QAAQ;AACP,YAAM,IAAI;AAAA,QACT;AAAA,oBAA0D,SAAS;AAAA;AAAA;AAAA,MACpE;AAAA,IACD;AAAA,EACD;AACD;AAEA,IAAM,QAAQ,gBAAgB;AAM9B,IAAM,wBAAN,MAAyD;AAAA,EAChD,SAAyB,CAAC;AAAA,EAC1B,kBAA4C;AAAA,EAC5C,qBAAkD;AAAA;AAAA;AAAA;AAAA,EAKnD,eAAe,QAA8B;AACnD,QAAI,OAAO,WAAW,YAAY,WAAW,MAAM;AAClD,YAAM,IAAI,UAAU,0BAA0B;AAAA,IAC/C;AACA,SAAK,SAAS;AACd,UAAM,eAAe;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA,EAKO,gBAAsB;AAC5B,UAAM,cAAc;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA,EAKO,YAAY,UAAmC;AACrD,QAAI,OAAO,aAAa,YAAY;AACnC,YAAM,IAAI,UAAU,6BAA6B;AAAA,IAClD;AACA,SAAK,kBAAkB;AAGvB,UAAM,YAAY,CAAC,WAAuB;AACzC,UAAI,mBAAmB,QAAQ,KAAK,MAAM,GAAG;AAC5C,cAAM,iBAAiB,wBAAwB,QAAQ,KAAK,MAAM;AAClE,aAAK,kBAAkB,cAAc;AAAA,MACtC;AAAA,IACD,CAAC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,eAAe,UAAsC;AAC3D,QAAI,OAAO,aAAa,YAAY;AACnC,YAAM,IAAI,UAAU,6BAA6B;AAAA,IAClD;AACA,SAAK,qBAAqB;AAG1B,UAAM,eAAe,CAAC,WAAuB;AAC5C,UAAI,mBAAmB,QAAQ,KAAK,MAAM,GAAG;AAC5C,cAAM,iBAAiB,wBAAwB,QAAQ,KAAK,MAAM;AAClE,aAAK,qBAAqB,cAAc;AAAA,MACzC;AAAA,IACD,CAAC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,cAA4B;AAClC,WAAO,MAAM,YAAY;AAAA,EAC1B;AACD;AAGA,IAAM,oBAAuC,IAAI,sBAAsB;AAEvE,IAAO,gBAAQ;",
+  "names": ["require"]
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@mcesystems/usb-device-listener",
+	"version": "1.0.0",
+	"description": "Native Windows USB device listener using PnP notifications without custom drivers",
+	"type": "module",
+	"main": "index.js",
+	"types": "index.d.ts",
+	"exports": {
+		".": {
+			"import": "./index.js",
+			"types": "./index.d.ts"
+		}
+	},
+	"keywords": [
+		"usb",
+		"device",
+		"listener",
+		"monitor",
+		"hotplug",
+		"pnp",
+		"windows",
+		"native",
+		"addon",
+		"n-api",
+		"typescript",
+		"esm",
+		"device-detection",
+		"hardware"
+	],
+	"author": "USB Device Listener Contributors",
+	"license": "ISC",
+	"dependencies": {
+		"node-addon-api": "^8.2.1"
+	},
+	"files": ["*.js", "*.d.ts", "*.d.ts.map", "*.js.map", "examples", "build"],
+	"os": ["win32"],
+	"engines": {
+		"node": ">=20.0.0"
+	}
+}

package/types.d.ts

@@ -0,0 +1,195 @@
+/**
+ * USB Device Listener Type Definitions
+ *
+ * Type-safe interface for monitoring USB device connections and disconnections
+ */
+/**
+ * Device information returned by the listener
+ */
+export interface DeviceInfo {
+    /**
+     * Windows device instance ID
+     * Format: "USB\VID_xxxx&PID_xxxx\..."
+     */
+    deviceId: string;
+    /**
+     * USB Vendor ID (decimal)
+     * Use .toString(16) to convert to hex string
+     */
+    vid: number;
+    /**
+     * USB Product ID (decimal)
+     * Use .toString(16) to convert to hex string
+     */
+    pid: number;
+    /**
+     * Physical USB port location
+     * Format: "Port_#xxxx.Hub_#yyyy"
+     * This value is stable and can be used as a key for logical port mapping
+     */
+    locationInfo: string;
+    /**
+     * User-defined logical port number from configuration
+     * null if not mapped in logicalPortMap
+     */
+    logicalPort: number | null;
+}
+/**
+ * Target device filter by VID/PID
+ */
+export interface TargetDevice {
+    /**
+     * USB Vendor ID as hex string (e.g., "04E8")
+     */
+    vid: string;
+    /**
+     * USB Product ID as hex string (e.g., "6860")
+     */
+    pid: string;
+}
+/**
+ * Configuration for USB device listener
+ */
+export interface ListenerConfig {
+    /**
+     * Map physical port locations to logical port numbers
+     *
+     * Key: Location info string (e.g., "Port_#0005.Hub_#0002")
+     * Value: Logical port number (e.g., 1, 2, 3)
+     *
+     * Use listDevices() to discover location strings for your setup
+     *
+     * @example
+     * {
+     *   "Port_#0005.Hub_#0002": 1,
+     *   "Port_#0006.Hub_#0002": 2
+     * }
+     */
+    logicalPortMap?: Record<string, number>;
+    /**
+     * Filter to monitor only specific devices by VID/PID
+     *
+     * Empty array or undefined = monitor all USB devices
+     *
+     * @example
+     * [
+     *   { vid: "04E8", pid: "6860" },  // Samsung device
+     *   { vid: "2341", pid: "0043" }   // Arduino Uno
+     * ]
+     */
+    targetDevices?: TargetDevice[];
+    /**
+     * Devices to ignore by VID/PID
+     *
+     * Devices matching any entry will not trigger events,
+     * even if they match other filters.
+     * This takes highest priority over all other filters.
+     *
+     * @example
+     * [
+     *   { vid: "1234", pid: "5678" }  // Ignore this specific device
+     * ]
+     */
+    ignoredDevices?: TargetDevice[];
+    /**
+     * Only monitor these specific devices by VID/PID
+     *
+     * Empty array or undefined = monitor all devices (subject to other filters)
+     * When set, only devices matching an entry will trigger events.
+     *
+     * @example
+     * [
+     *   { vid: "04E8", pid: "6860" }  // Only listen to this device
+     * ]
+     */
+    listenOnlyDevices?: TargetDevice[];
+}
+/**
+ * Callback type for device add events
+ */
+export type DeviceAddCallback = (deviceInfo: DeviceInfo) => void;
+/**
+ * Callback type for device remove events
+ */
+export type DeviceRemoveCallback = (deviceInfo: DeviceInfo) => void;
+/**
+ * USB Device Listener Module
+ */
+export interface UsbDeviceListener {
+    /**
+     * Start listening for USB device events
+     *
+     * Creates a background thread that monitors Windows device change messages.
+     * Callbacks registered with onDeviceAdd/onDeviceRemove will be invoked
+     * when matching devices are connected or disconnected.
+     *
+     * @param config - Listener configuration
+     * @throws {TypeError} If config is not an object
+     * @throws {Error} If listener is already running
+     *
+     * @example
+     * listener.startListening({
+     *   logicalPortMap: { "Port_#0005.Hub_#0002": 1 },
+     *   targetDevices: [{ vid: "04E8", pid: "6860" }]
+     * });
+     */
+    startListening(config: ListenerConfig): void;
+    /**
+     * Stop listening for USB device events
+     *
+     * Stops the background thread and cleans up resources.
+     * Safe to call multiple times.
+     *
+     * @example
+     * listener.stopListening();
+     */
+    stopListening(): void;
+    /**
+     * Register callback for device connection events
+     *
+     * The callback will be invoked on the Node.js main thread whenever
+     * a matching USB device is connected.
+     *
+     * @param callback - Function to call when device is connected
+     * @throws {TypeError} If callback is not a function
+     *
+     * @example
+     * listener.onDeviceAdd((device) => {
+     *   console.log(`Device ${device.vid.toString(16)}:${device.pid.toString(16)}`);
+     *   console.log(`Connected to port ${device.logicalPort}`);
+     * });
+     */
+    onDeviceAdd(callback: DeviceAddCallback): void;
+    /**
+     * Register callback for device disconnection events
+     *
+     * The callback will be invoked on the Node.js main thread whenever
+     * a matching USB device is disconnected.
+     *
+     * @param callback - Function to call when device is disconnected
+     * @throws {TypeError} If callback is not a function
+     *
+     * @example
+     * listener.onDeviceRemove((device) => {
+     *   console.log(`Port ${device.logicalPort} disconnected`);
+     * });
+     */
+    onDeviceRemove(callback: DeviceRemoveCallback): void;
+    /**
+     * List all currently connected USB devices
+     *
+     * Returns information about all USB devices currently connected to the system.
+     * Useful for discovering device locations and initial state.
+     *
+     * @returns Array of device information objects
+     *
+     * @example
+     * const devices = listener.listDevices();
+     * devices.forEach(device => {
+     *   console.log(`Location: ${device.locationInfo}`);
+     *   console.log(`VID:PID = ${device.vid.toString(16)}:${device.pid.toString(16)}`);
+     * });
+     */
+    listDevices(): DeviceInfo[];
+}
+//# sourceMappingURL=types.d.ts.map

package/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAE/B;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,YAAY,EAAE,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,YAAY,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAE7C;;;;;;;;OAQG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE/C;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAErD;;;;;;;;;;;;;;OAcG;IACH,WAAW,IAAI,UAAU,EAAE,CAAC;CAC5B"}