@mcesystems/usb-device-listener 1.0.76 → 1.0.78

package/README.md

@@ -125,6 +125,10 @@ Start monitoring USB device events.
   - `logicalPortMap` (Object, optional): Map physical locations to logical port numbers
     - Key: Location string (platform-specific format)
     - Value: Logical port number (integer)
+  - `logicalPortMapByHub` (Object, optional): Map physical port to logical port per hub (alternative to logicalPortMap)
+    - Key: Hub identifier `"${vid}-${pid}"` (hex, uppercase 4-char, e.g. `"1A2C-3B4D"`)
+    - Value: Object mapping physical port number to logical port number (e.g. `{ 1: 4, 4: 2, 3: 3, 2: 1 }`)
+    - When both `logicalPortMap` and `logicalPortMapByHub` could apply, `logicalPortMapByHub` takes precedence when the device has hub data (`portPath`, `parentHubVid`, `parentHubPid`)
   - `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
@@ -203,6 +207,9 @@ Register callback for device connection events.
     - `pid` (number): Product ID (decimal)
     - `locationInfo` (string): Physical port location (platform-specific format)
     - `logicalPort` (number|null): Mapped logical port or null
+    - `portPath` (number[]|undefined): Port path from root to device (e.g. [2, 3, 1]); present when native layer provides it (e.g. Windows)
+    - `parentHubVid` (number|undefined): VID of hub the device is directly connected to (0 if on root)
+    - `parentHubPid` (number|undefined): PID of that hub
 
 **Example:**
 ```javascript
@@ -277,18 +284,20 @@ Use the included `list-devices.js` utility:
 node list-devices.js
 ```
 
-**Windows output:**
+**Windows output** (when port path is available, `Port path (tree)` shows the chain, e.g. 2/3/1 = port 2, then 3, then 1):
 ```
 Device 1:
   Device ID: USB\VID_04E8&PID_6860\R58NC2971AJ
   VID: 0x04E8
   PID: 0x6860
+  Port path (tree): 2/3/1
   Location Info (mapping key): Port_#0005.Hub_#0002
 
 Device 2:
   Device ID: USB\VID_27C6&PID_6594\UID0014C59F
   VID: 0x27C6
   PID: 0x6594
+  Port path (tree): 2/7
   Location Info (mapping key): Port_#0007.Hub_#0002
 ```
 
@@ -307,7 +316,9 @@ Device 2:
   Location Info (mapping key): Port_#14100000
 ```
 
-Copy the "Location Info" values to use in your `logicalPortMap`.
+Copy the "Location Info" values to use in your `logicalPortMap`. When available, use **Port path (tree)** and the parent hub (from list output or `parentHubVid`/`parentHubPid`) with `logicalPortMapByHub`.
+
+**Helper:** `formatPortPath(device)` returns the port path as a string (e.g. `"2/3/1"`) or falls back to `locationInfo` when port path is not available.
 
 ### Device Filtering
 

package/dist/device-filter.d.ts

@@ -6,7 +6,7 @@ import type { DeviceInfo, ListenerConfig } from "./types";
  * 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
+ * 4. logicalPortMap / logicalPortMapByHub - if specified, device must be in the map (hub map takes precedence when device has hub data)
  *
  * @param device - The device information from the native addon
  * @param config - The listener configuration
@@ -14,7 +14,8 @@ import type { DeviceInfo, ListenerConfig } from "./types";
  */
 export declare function shouldNotifyDevice(device: DeviceInfo, config: ListenerConfig): boolean;
 /**
- * Apply logical port mapping to a device if configured
+ * Apply logical port mapping to a device if configured.
+ * logicalPortMapByHub takes precedence when device has parent hub and port path.
  *
  * @param device - The device information from the native addon
  * @param config - The listener configuration

package/dist/device-filter.d.ts.map

@@ -1 +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"}
+{"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;AAoDxE;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAuCtF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,UAAU,CA2B9F"}

package/dist/formatPortPath.d.ts

@@ -0,0 +1,10 @@
+import type { DeviceInfo } from "./types.js";
+/**
+ * Format device port path for display (e.g. "2/3/1" for port 2, then 3, then 1).
+ * When portPath is available, returns slash-separated port numbers; otherwise returns locationInfo.
+ *
+ * @param device - Device info from the listener
+ * @returns Port path string (e.g. "2/3/1") or locationInfo fallback
+ */
+export declare function formatPortPath(device: DeviceInfo): string;
+//# sourceMappingURL=formatPortPath.d.ts.map

package/dist/formatPortPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatPortPath.d.ts","sourceRoot":"","sources":["../src/formatPortPath.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAKzD"}

package/dist/index.d.ts

@@ -49,5 +49,6 @@ export default class UsbDeviceListener implements UsbDeviceListenerI {
      */
     listDevices(): DeviceInfo[];
 }
+export { formatPortPath } from "./formatPortPath.js";
 export type { DeviceInfo, DeviceAddCallback, DeviceRemoveCallback, ListenerConfig, TargetDevice, } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACX,iBAAiB,EACjB,UAAU,EACV,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,WAAW;IAC3B,cAAc,IAAI,IAAI,CAAC;IACvB,aAAa,IAAI,IAAI,CAAC;IACtB,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/C,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACrD,WAAW,IAAI,UAAU,EAAE,CAAC;CAC5B;AAUD;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAkB,YAAW,kBAAkB;IACnE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,kBAAkB,CAAqC;gBAEnD,KAAK,CAAC,EAAE,WAAW;IAI/B;;OAEG;IACI,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAQnD;;OAEG;IACI,aAAa,IAAI,IAAI;IAI5B;;;;OAIG;IACI,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAOjD;;;OAGG;IACI,gBAAgB,IAAI,cAAc;IAIzC;;OAEG;IACI,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAerD;;OAEG;IACI,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAe3D;;;OAGG;IACI,WAAW,IAAI,UAAU,EAAE;CAKlC;AAED,YAAY,EACX,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,YAAY,GACZ,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACX,iBAAiB,EACjB,UAAU,EACV,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,WAAW;IAC3B,cAAc,IAAI,IAAI,CAAC;IACvB,aAAa,IAAI,IAAI,CAAC;IACtB,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/C,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACrD,WAAW,IAAI,UAAU,EAAE,CAAC;CAC5B;AAUD;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAkB,YAAW,kBAAkB;IACnE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,kBAAkB,CAAqC;gBAEnD,KAAK,CAAC,EAAE,WAAW;IAI/B;;OAEG;IACI,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAQnD;;OAEG;IACI,aAAa,IAAI,IAAI;IAI5B;;;;OAIG;IACI,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAOjD;;;OAGG;IACI,gBAAgB,IAAI,cAAc;IAIzC;;OAEG;IACI,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAerD;;OAEG;IACI,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAe3D;;;OAGG;IACI,WAAW,IAAI,UAAU,EAAE;CAKlC;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EACX,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,YAAY,GACZ,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -31,7 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  default: () => UsbDeviceListener
+  default: () => UsbDeviceListener,
+  formatPortPath: () => formatPortPath
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_module = require("node:module");
@@ -52,6 +53,22 @@ function matchesDevice(device, target) {
 function matchesAnyDevice(device, targets) {
   return targets.some((target) => matchesDevice(device, target));
 }
+function hubKeyFromParent(vid, pid) {
+  return `${vid.toString(16).toUpperCase().padStart(4, "0")}-${pid.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+function isMappedInLogicalPortMapByHub(device, config) {
+  const map = config.logicalPortMapByHub;
+  if (!map || Object.keys(map).length === 0) return false;
+  const vid = device.parentHubVid;
+  const pid = device.parentHubPid;
+  const path2 = device.portPath;
+  if (vid === void 0 || pid === void 0 || !path2 || path2.length === 0) return false;
+  const key = hubKeyFromParent(vid, pid);
+  const portMap = map[key];
+  if (!portMap) return false;
+  const physicalPort = path2[path2.length - 1];
+  return physicalPort in portMap;
+}
 function shouldNotifyDevice(device, config) {
   if (config.ignoredDevices && config.ignoredDevices.length > 0) {
     if (matchesAnyDevice(device, config.ignoredDevices)) {
@@ -68,14 +85,34 @@ function shouldNotifyDevice(device, config) {
       return false;
     }
   }
-  if (config.logicalPortMap && Object.keys(config.logicalPortMap).length > 0) {
+  const hasHubMap = config.logicalPortMapByHub && Object.keys(config.logicalPortMapByHub).length > 0;
+  const hasLocationMap = config.logicalPortMap && Object.keys(config.logicalPortMap).length > 0;
+  if (hasHubMap && device.parentHubVid !== void 0 && device.parentHubPid !== void 0 && device.portPath && device.portPath.length > 0) {
+    if (!isMappedInLogicalPortMapByHub(device, config)) {
+      return false;
+    }
+  } else if (hasLocationMap && config.logicalPortMap) {
     if (!(device.locationInfo in config.logicalPortMap)) {
       return false;
     }
+  } else if (hasHubMap) {
+    return false;
   }
   return true;
 }
 function applyLogicalPortMapping(device, config) {
+  const mapByHub = config.logicalPortMapByHub;
+  if (mapByHub && Object.keys(mapByHub).length > 0 && device.parentHubVid !== void 0 && device.parentHubPid !== void 0 && device.portPath && device.portPath.length > 0) {
+    const key = hubKeyFromParent(device.parentHubVid, device.parentHubPid);
+    const portMap = mapByHub[key];
+    const physicalPort = device.portPath[device.portPath.length - 1];
+    if (portMap && physicalPort in portMap) {
+      return {
+        ...device,
+        logicalPort: portMap[physicalPort]
+      };
+    }
+  }
   if (config.logicalPortMap && device.locationInfo in config.logicalPortMap) {
     return {
       ...device,
@@ -85,6 +122,14 @@ function applyLogicalPortMapping(device, config) {
   return device;
 }
 
+// src/formatPortPath.ts
+function formatPortPath(device) {
+  if (device.portPath && device.portPath.length > 0) {
+    return device.portPath.join("/");
+  }
+  return device.locationInfo;
+}
+
 // src/index.ts
 function loadDefaultAddon() {
   const require2 = (0, import_node_module.createRequire)(__importMetaUrl);
@@ -174,5 +219,9 @@ var UsbDeviceListener = class {
     return devices.map((device) => applyLogicalPortMapping(device, this.config));
   }
 };
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  formatPortPath
+});
 module.exports = Object.assign(module.exports.default, module.exports);
 //# sourceMappingURL=index.js.map

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\";\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\nexport interface NativeAddon {\n\tstartListening(): void;\n\tstopListening(): void;\n\tonDeviceAdd(callback: DeviceAddCallback): void;\n\tonDeviceRemove(callback: DeviceRemoveCallback): void;\n\tlistDevices(): DeviceInfo[];\n}\n\nfunction loadDefaultAddon(): NativeAddon {\n\tconst require = createRequire(import.meta.url);\n\tconst __filename = fileURLToPath(import.meta.url);\n\tconst __dirname = path.dirname(__filename);\n\tconst packageRoot = path.join(__dirname, \"..\");\n\treturn require(\"node-gyp-build\")(packageRoot);\n}\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 readonly addon: NativeAddon;\n\tprivate config: ListenerConfig = {};\n\tprivate userAddCallback: DeviceAddCallback | null = null;\n\tprivate userRemoveCallback: DeviceRemoveCallback | null = null;\n\n\tconstructor(addon?: NativeAddon) {\n\t\tthis.addon = addon ?? loadDefaultAddon();\n\t}\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\tthis.addon.startListening();\n\t}\n\n\t/**\n\t * Stop listening for USB device events\n\t */\n\tpublic stopListening(): void {\n\t\tthis.addon.stopListening();\n\t}\n\n\t/**\n\t * Update the listener config at runtime.\n\t * When listening, subsequent device events and listDevices() use the new config.\n\t * When not listening, only listDevices() uses it until the next startListening().\n\t */\n\tpublic updateConfig(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}\n\n\t/**\n\t * Return a shallow copy of the current config.\n\t * Mutating the returned object does not affect the listener's internal config.\n\t */\n\tpublic getCurrentConfig(): ListenerConfig {\n\t\treturn { ...this.config };\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\tthis.addon.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\tthis.addon.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 * Applies logical port mapping from config if set\n\t */\n\tpublic listDevices(): DeviceInfo[] {\n\t\tconst devices = this.addon.listDevices();\n\t\t// Apply logical port mapping to each device\n\t\treturn devices.map((device) => applyLogicalPortMapping(device, this.config));\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": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAA8B;AAC9B,uBAAiB;AACjB,sBAA8B;;;ACG9B,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;;;ADpEA,SAAS,mBAAgC;AACxC,QAAMA,eAAU,kCAAc,eAAe;AAC7C,QAAM,iBAAa,+BAAc,eAAe;AAChD,QAAM,YAAY,iBAAAC,QAAK,QAAQ,UAAU;AACzC,QAAM,cAAc,iBAAAA,QAAK,KAAK,WAAW,IAAI;AAC7C,SAAOD,SAAQ,gBAAgB,EAAE,WAAW;AAC7C;AAMA,IAAqB,oBAArB,MAAqE;AAAA,EACnD;AAAA,EACT,SAAyB,CAAC;AAAA,EAC1B,kBAA4C;AAAA,EAC5C,qBAAkD;AAAA,EAE1D,YAAY,OAAqB;AAChC,SAAK,QAAQ,SAAS,iBAAiB;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA,EAKO,eAAe,QAA8B;AACnD,QAAI,OAAO,WAAW,YAAY,WAAW,MAAM;AAClD,YAAM,IAAI,UAAU,0BAA0B;AAAA,IAC/C;AACA,SAAK,SAAS;AACd,SAAK,MAAM,eAAe;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA,EAKO,gBAAsB;AAC5B,SAAK,MAAM,cAAc;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,aAAa,QAA8B;AACjD,QAAI,OAAO,WAAW,YAAY,WAAW,MAAM;AAClD,YAAM,IAAI,UAAU,0BAA0B;AAAA,IAC/C;AACA,SAAK,SAAS;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,mBAAmC;AACzC,WAAO,EAAE,GAAG,KAAK,OAAO;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA,EAKO,YAAY,UAAmC;AACrD,QAAI,OAAO,aAAa,YAAY;AACnC,YAAM,IAAI,UAAU,6BAA6B;AAAA,IAClD;AACA,SAAK,kBAAkB;AAGvB,SAAK,MAAM,YAAY,CAAC,WAAuB;AAC9C,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,SAAK,MAAM,eAAe,CAAC,WAAuB;AACjD,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;AAAA,EAMO,cAA4B;AAClC,UAAM,UAAU,KAAK,MAAM,YAAY;AAEvC,WAAO,QAAQ,IAAI,CAAC,WAAW,wBAAwB,QAAQ,KAAK,MAAM,CAAC;AAAA,EAC5E;AACD;",
-  "names": ["require", "path"]
+  "sources": ["../src/index.ts", "../src/device-filter.ts", "../src/formatPortPath.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\nexport interface NativeAddon {\n\tstartListening(): void;\n\tstopListening(): void;\n\tonDeviceAdd(callback: DeviceAddCallback): void;\n\tonDeviceRemove(callback: DeviceRemoveCallback): void;\n\tlistDevices(): DeviceInfo[];\n}\n\nfunction loadDefaultAddon(): NativeAddon {\n\tconst require = createRequire(import.meta.url);\n\tconst __filename = fileURLToPath(import.meta.url);\n\tconst __dirname = path.dirname(__filename);\n\tconst packageRoot = path.join(__dirname, \"..\");\n\treturn require(\"node-gyp-build\")(packageRoot);\n}\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 readonly addon: NativeAddon;\n\tprivate config: ListenerConfig = {};\n\tprivate userAddCallback: DeviceAddCallback | null = null;\n\tprivate userRemoveCallback: DeviceRemoveCallback | null = null;\n\n\tconstructor(addon?: NativeAddon) {\n\t\tthis.addon = addon ?? loadDefaultAddon();\n\t}\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\tthis.addon.startListening();\n\t}\n\n\t/**\n\t * Stop listening for USB device events\n\t */\n\tpublic stopListening(): void {\n\t\tthis.addon.stopListening();\n\t}\n\n\t/**\n\t * Update the listener config at runtime.\n\t * When listening, subsequent device events and listDevices() use the new config.\n\t * When not listening, only listDevices() uses it until the next startListening().\n\t */\n\tpublic updateConfig(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}\n\n\t/**\n\t * Return a shallow copy of the current config.\n\t * Mutating the returned object does not affect the listener's internal config.\n\t */\n\tpublic getCurrentConfig(): ListenerConfig {\n\t\treturn { ...this.config };\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\tthis.addon.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\tthis.addon.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 * Applies logical port mapping from config if set\n\t */\n\tpublic listDevices(): DeviceInfo[] {\n\t\tconst devices = this.addon.listDevices();\n\t\t// Apply logical port mapping to each device\n\t\treturn devices.map((device) => applyLogicalPortMapping(device, this.config));\n\t}\n}\n\nexport { formatPortPath } from \"./formatPortPath.js\";\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 * Build hub key \"${vid}-${pid}\" from device's parent hub (uppercase 4-char hex).\n */\nfunction hubKeyFromParent(vid: number, pid: number): string {\n\treturn `${vid.toString(16).toUpperCase().padStart(4, \"0\")}-${pid.toString(16).toUpperCase().padStart(4, \"0\")}`;\n}\n\n/**\n * True if device has parent hub data and is mapped in logicalPortMapByHub.\n */\nfunction isMappedInLogicalPortMapByHub(device: DeviceInfo, config: ListenerConfig): boolean {\n\tconst map = config.logicalPortMapByHub;\n\tif (!map || Object.keys(map).length === 0) return false;\n\tconst vid = device.parentHubVid;\n\tconst pid = device.parentHubPid;\n\tconst path = device.portPath;\n\tif (vid === undefined || pid === undefined || !path || path.length === 0) return false;\n\tconst key = hubKeyFromParent(vid, pid);\n\tconst portMap = map[key];\n\tif (!portMap) return false;\n\tconst physicalPort = path[path.length - 1];\n\treturn physicalPort in portMap;\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 / logicalPortMapByHub - if specified, device must be in the map (hub map takes precedence when device has hub data)\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 / logicalPortMapByHub (if specified, device must be mapped)\n\tconst hasHubMap = config.logicalPortMapByHub && Object.keys(config.logicalPortMapByHub).length > 0;\n\tconst hasLocationMap = config.logicalPortMap && Object.keys(config.logicalPortMap).length > 0;\n\tif (hasHubMap && device.parentHubVid !== undefined && device.parentHubPid !== undefined && device.portPath && device.portPath.length > 0) {\n\t\tif (!isMappedInLogicalPortMapByHub(device, config)) {\n\t\t\treturn false;\n\t\t}\n\t} else if (hasLocationMap && config.logicalPortMap) {\n\t\tif (!(device.locationInfo in config.logicalPortMap)) {\n\t\t\treturn false;\n\t\t}\n\t} else if (hasHubMap) {\n\t\t// logicalPortMapByHub is set but device has no hub data - cannot be in map\n\t\treturn false;\n\t}\n\n\treturn true;\n}\n\n/**\n * Apply logical port mapping to a device if configured.\n * logicalPortMapByHub takes precedence when device has parent hub and port path.\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\tconst mapByHub = config.logicalPortMapByHub;\n\tif (\n\t\tmapByHub &&\n\t\tObject.keys(mapByHub).length > 0 &&\n\t\tdevice.parentHubVid !== undefined &&\n\t\tdevice.parentHubPid !== undefined &&\n\t\tdevice.portPath &&\n\t\tdevice.portPath.length > 0\n\t) {\n\t\tconst key = hubKeyFromParent(device.parentHubVid, device.parentHubPid);\n\t\tconst portMap = mapByHub[key];\n\t\tconst physicalPort = device.portPath[device.portPath.length - 1];\n\t\tif (portMap && physicalPort in portMap) {\n\t\t\treturn {\n\t\t\t\t...device,\n\t\t\t\tlogicalPort: portMap[physicalPort],\n\t\t\t};\n\t\t}\n\t}\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 type { DeviceInfo } from \"./types.js\";\n\n/**\n * Format device port path for display (e.g. \"2/3/1\" for port 2, then 3, then 1).\n * When portPath is available, returns slash-separated port numbers; otherwise returns locationInfo.\n *\n * @param device - Device info from the listener\n * @returns Port path string (e.g. \"2/3/1\") or locationInfo fallback\n */\nexport function formatPortPath(device: DeviceInfo): string {\n\tif (device.portPath && device.portPath.length > 0) {\n\t\treturn device.portPath.join(\"/\");\n\t}\n\treturn device.locationInfo;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAA8B;AAC9B,uBAAiB;AACjB,sBAA8B;;;ACG9B,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;AAKA,SAAS,iBAAiB,KAAa,KAAqB;AAC3D,SAAO,GAAG,IAAI,SAAS,EAAE,EAAE,YAAY,EAAE,SAAS,GAAG,GAAG,CAAC,IAAI,IAAI,SAAS,EAAE,EAAE,YAAY,EAAE,SAAS,GAAG,GAAG,CAAC;AAC7G;AAKA,SAAS,8BAA8B,QAAoB,QAAiC;AAC3F,QAAM,MAAM,OAAO;AACnB,MAAI,CAAC,OAAO,OAAO,KAAK,GAAG,EAAE,WAAW,EAAG,QAAO;AAClD,QAAM,MAAM,OAAO;AACnB,QAAM,MAAM,OAAO;AACnB,QAAMA,QAAO,OAAO;AACpB,MAAI,QAAQ,UAAa,QAAQ,UAAa,CAACA,SAAQA,MAAK,WAAW,EAAG,QAAO;AACjF,QAAM,MAAM,iBAAiB,KAAK,GAAG;AACrC,QAAM,UAAU,IAAI,GAAG;AACvB,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,eAAeA,MAAKA,MAAK,SAAS,CAAC;AACzC,SAAO,gBAAgB;AACxB;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,QAAM,YAAY,OAAO,uBAAuB,OAAO,KAAK,OAAO,mBAAmB,EAAE,SAAS;AACjG,QAAM,iBAAiB,OAAO,kBAAkB,OAAO,KAAK,OAAO,cAAc,EAAE,SAAS;AAC5F,MAAI,aAAa,OAAO,iBAAiB,UAAa,OAAO,iBAAiB,UAAa,OAAO,YAAY,OAAO,SAAS,SAAS,GAAG;AACzI,QAAI,CAAC,8BAA8B,QAAQ,MAAM,GAAG;AACnD,aAAO;AAAA,IACR;AAAA,EACD,WAAW,kBAAkB,OAAO,gBAAgB;AACnD,QAAI,EAAE,OAAO,gBAAgB,OAAO,iBAAiB;AACpD,aAAO;AAAA,IACR;AAAA,EACD,WAAW,WAAW;AAErB,WAAO;AAAA,EACR;AAEA,SAAO;AACR;AAUO,SAAS,wBAAwB,QAAoB,QAAoC;AAC/F,QAAM,WAAW,OAAO;AACxB,MACC,YACA,OAAO,KAAK,QAAQ,EAAE,SAAS,KAC/B,OAAO,iBAAiB,UACxB,OAAO,iBAAiB,UACxB,OAAO,YACP,OAAO,SAAS,SAAS,GACxB;AACD,UAAM,MAAM,iBAAiB,OAAO,cAAc,OAAO,YAAY;AACrE,UAAM,UAAU,SAAS,GAAG;AAC5B,UAAM,eAAe,OAAO,SAAS,OAAO,SAAS,SAAS,CAAC;AAC/D,QAAI,WAAW,gBAAgB,SAAS;AACvC,aAAO;AAAA,QACN,GAAG;AAAA,QACH,aAAa,QAAQ,YAAY;AAAA,MAClC;AAAA,IACD;AAAA,EACD;AACA,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;;;ACpIO,SAAS,eAAe,QAA4B;AAC1D,MAAI,OAAO,YAAY,OAAO,SAAS,SAAS,GAAG;AAClD,WAAO,OAAO,SAAS,KAAK,GAAG;AAAA,EAChC;AACA,SAAO,OAAO;AACf;;;AFMA,SAAS,mBAAgC;AACxC,QAAMC,eAAU,kCAAc,eAAe;AAC7C,QAAM,iBAAa,+BAAc,eAAe;AAChD,QAAM,YAAY,iBAAAC,QAAK,QAAQ,UAAU;AACzC,QAAM,cAAc,iBAAAA,QAAK,KAAK,WAAW,IAAI;AAC7C,SAAOD,SAAQ,gBAAgB,EAAE,WAAW;AAC7C;AAMA,IAAqB,oBAArB,MAAqE;AAAA,EACnD;AAAA,EACT,SAAyB,CAAC;AAAA,EAC1B,kBAA4C;AAAA,EAC5C,qBAAkD;AAAA,EAE1D,YAAY,OAAqB;AAChC,SAAK,QAAQ,SAAS,iBAAiB;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA,EAKO,eAAe,QAA8B;AACnD,QAAI,OAAO,WAAW,YAAY,WAAW,MAAM;AAClD,YAAM,IAAI,UAAU,0BAA0B;AAAA,IAC/C;AACA,SAAK,SAAS;AACd,SAAK,MAAM,eAAe;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA,EAKO,gBAAsB;AAC5B,SAAK,MAAM,cAAc;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,aAAa,QAA8B;AACjD,QAAI,OAAO,WAAW,YAAY,WAAW,MAAM;AAClD,YAAM,IAAI,UAAU,0BAA0B;AAAA,IAC/C;AACA,SAAK,SAAS;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,mBAAmC;AACzC,WAAO,EAAE,GAAG,KAAK,OAAO;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA,EAKO,YAAY,UAAmC;AACrD,QAAI,OAAO,aAAa,YAAY;AACnC,YAAM,IAAI,UAAU,6BAA6B;AAAA,IAClD;AACA,SAAK,kBAAkB;AAGvB,SAAK,MAAM,YAAY,CAAC,WAAuB;AAC9C,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,SAAK,MAAM,eAAe,CAAC,WAAuB;AACjD,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;AAAA,EAMO,cAA4B;AAClC,UAAM,UAAU,KAAK,MAAM,YAAY;AAEvC,WAAO,QAAQ,IAAI,CAAC,WAAW,wBAAwB,QAAQ,KAAK,MAAM,CAAC;AAAA,EAC5E;AACD;",
+  "names": ["path", "require", "path"]
 }

package/dist/index.mjs

@@ -17,6 +17,22 @@ function matchesDevice(device, target) {
 function matchesAnyDevice(device, targets) {
   return targets.some((target) => matchesDevice(device, target));
 }
+function hubKeyFromParent(vid, pid) {
+  return `${vid.toString(16).toUpperCase().padStart(4, "0")}-${pid.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+function isMappedInLogicalPortMapByHub(device, config) {
+  const map = config.logicalPortMapByHub;
+  if (!map || Object.keys(map).length === 0) return false;
+  const vid = device.parentHubVid;
+  const pid = device.parentHubPid;
+  const path2 = device.portPath;
+  if (vid === void 0 || pid === void 0 || !path2 || path2.length === 0) return false;
+  const key = hubKeyFromParent(vid, pid);
+  const portMap = map[key];
+  if (!portMap) return false;
+  const physicalPort = path2[path2.length - 1];
+  return physicalPort in portMap;
+}
 function shouldNotifyDevice(device, config) {
   if (config.ignoredDevices && config.ignoredDevices.length > 0) {
     if (matchesAnyDevice(device, config.ignoredDevices)) {
@@ -33,14 +49,34 @@ function shouldNotifyDevice(device, config) {
       return false;
     }
   }
-  if (config.logicalPortMap && Object.keys(config.logicalPortMap).length > 0) {
+  const hasHubMap = config.logicalPortMapByHub && Object.keys(config.logicalPortMapByHub).length > 0;
+  const hasLocationMap = config.logicalPortMap && Object.keys(config.logicalPortMap).length > 0;
+  if (hasHubMap && device.parentHubVid !== void 0 && device.parentHubPid !== void 0 && device.portPath && device.portPath.length > 0) {
+    if (!isMappedInLogicalPortMapByHub(device, config)) {
+      return false;
+    }
+  } else if (hasLocationMap && config.logicalPortMap) {
     if (!(device.locationInfo in config.logicalPortMap)) {
       return false;
     }
+  } else if (hasHubMap) {
+    return false;
   }
   return true;
 }
 function applyLogicalPortMapping(device, config) {
+  const mapByHub = config.logicalPortMapByHub;
+  if (mapByHub && Object.keys(mapByHub).length > 0 && device.parentHubVid !== void 0 && device.parentHubPid !== void 0 && device.portPath && device.portPath.length > 0) {
+    const key = hubKeyFromParent(device.parentHubVid, device.parentHubPid);
+    const portMap = mapByHub[key];
+    const physicalPort = device.portPath[device.portPath.length - 1];
+    if (portMap && physicalPort in portMap) {
+      return {
+        ...device,
+        logicalPort: portMap[physicalPort]
+      };
+    }
+  }
   if (config.logicalPortMap && device.locationInfo in config.logicalPortMap) {
     return {
       ...device,
@@ -50,6 +86,14 @@ function applyLogicalPortMapping(device, config) {
   return device;
 }
 
+// src/formatPortPath.ts
+function formatPortPath(device) {
+  if (device.portPath && device.portPath.length > 0) {
+    return device.portPath.join("/");
+  }
+  return device.locationInfo;
+}
+
 // src/index.ts
 function loadDefaultAddon() {
   const require2 = createRequire(import.meta.url);
@@ -140,6 +184,7 @@ var UsbDeviceListener = class {
   }
 };
 export {
-  UsbDeviceListener as default
+  UsbDeviceListener as default,
+  formatPortPath
 };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1,7 +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\nexport interface NativeAddon {\n\tstartListening(): void;\n\tstopListening(): void;\n\tonDeviceAdd(callback: DeviceAddCallback): void;\n\tonDeviceRemove(callback: DeviceRemoveCallback): void;\n\tlistDevices(): DeviceInfo[];\n}\n\nfunction loadDefaultAddon(): NativeAddon {\n\tconst require = createRequire(import.meta.url);\n\tconst __filename = fileURLToPath(import.meta.url);\n\tconst __dirname = path.dirname(__filename);\n\tconst packageRoot = path.join(__dirname, \"..\");\n\treturn require(\"node-gyp-build\")(packageRoot);\n}\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 readonly addon: NativeAddon;\n\tprivate config: ListenerConfig = {};\n\tprivate userAddCallback: DeviceAddCallback | null = null;\n\tprivate userRemoveCallback: DeviceRemoveCallback | null = null;\n\n\tconstructor(addon?: NativeAddon) {\n\t\tthis.addon = addon ?? loadDefaultAddon();\n\t}\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\tthis.addon.startListening();\n\t}\n\n\t/**\n\t * Stop listening for USB device events\n\t */\n\tpublic stopListening(): void {\n\t\tthis.addon.stopListening();\n\t}\n\n\t/**\n\t * Update the listener config at runtime.\n\t * When listening, subsequent device events and listDevices() use the new config.\n\t * When not listening, only listDevices() uses it until the next startListening().\n\t */\n\tpublic updateConfig(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}\n\n\t/**\n\t * Return a shallow copy of the current config.\n\t * Mutating the returned object does not affect the listener's internal config.\n\t */\n\tpublic getCurrentConfig(): ListenerConfig {\n\t\treturn { ...this.config };\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\tthis.addon.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\tthis.addon.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 * Applies logical port mapping from config if set\n\t */\n\tpublic listDevices(): DeviceInfo[] {\n\t\tconst devices = this.addon.listDevices();\n\t\t// Apply logical port mapping to each device\n\t\treturn devices.map((device) => applyLogicalPortMapping(device, this.config));\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"]
+  "sources": ["../src/index.ts", "../src/device-filter.ts", "../src/formatPortPath.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\nexport interface NativeAddon {\n\tstartListening(): void;\n\tstopListening(): void;\n\tonDeviceAdd(callback: DeviceAddCallback): void;\n\tonDeviceRemove(callback: DeviceRemoveCallback): void;\n\tlistDevices(): DeviceInfo[];\n}\n\nfunction loadDefaultAddon(): NativeAddon {\n\tconst require = createRequire(import.meta.url);\n\tconst __filename = fileURLToPath(import.meta.url);\n\tconst __dirname = path.dirname(__filename);\n\tconst packageRoot = path.join(__dirname, \"..\");\n\treturn require(\"node-gyp-build\")(packageRoot);\n}\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 readonly addon: NativeAddon;\n\tprivate config: ListenerConfig = {};\n\tprivate userAddCallback: DeviceAddCallback | null = null;\n\tprivate userRemoveCallback: DeviceRemoveCallback | null = null;\n\n\tconstructor(addon?: NativeAddon) {\n\t\tthis.addon = addon ?? loadDefaultAddon();\n\t}\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\tthis.addon.startListening();\n\t}\n\n\t/**\n\t * Stop listening for USB device events\n\t */\n\tpublic stopListening(): void {\n\t\tthis.addon.stopListening();\n\t}\n\n\t/**\n\t * Update the listener config at runtime.\n\t * When listening, subsequent device events and listDevices() use the new config.\n\t * When not listening, only listDevices() uses it until the next startListening().\n\t */\n\tpublic updateConfig(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}\n\n\t/**\n\t * Return a shallow copy of the current config.\n\t * Mutating the returned object does not affect the listener's internal config.\n\t */\n\tpublic getCurrentConfig(): ListenerConfig {\n\t\treturn { ...this.config };\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\tthis.addon.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\tthis.addon.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 * Applies logical port mapping from config if set\n\t */\n\tpublic listDevices(): DeviceInfo[] {\n\t\tconst devices = this.addon.listDevices();\n\t\t// Apply logical port mapping to each device\n\t\treturn devices.map((device) => applyLogicalPortMapping(device, this.config));\n\t}\n}\n\nexport { formatPortPath } from \"./formatPortPath.js\";\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 * Build hub key \"${vid}-${pid}\" from device's parent hub (uppercase 4-char hex).\n */\nfunction hubKeyFromParent(vid: number, pid: number): string {\n\treturn `${vid.toString(16).toUpperCase().padStart(4, \"0\")}-${pid.toString(16).toUpperCase().padStart(4, \"0\")}`;\n}\n\n/**\n * True if device has parent hub data and is mapped in logicalPortMapByHub.\n */\nfunction isMappedInLogicalPortMapByHub(device: DeviceInfo, config: ListenerConfig): boolean {\n\tconst map = config.logicalPortMapByHub;\n\tif (!map || Object.keys(map).length === 0) return false;\n\tconst vid = device.parentHubVid;\n\tconst pid = device.parentHubPid;\n\tconst path = device.portPath;\n\tif (vid === undefined || pid === undefined || !path || path.length === 0) return false;\n\tconst key = hubKeyFromParent(vid, pid);\n\tconst portMap = map[key];\n\tif (!portMap) return false;\n\tconst physicalPort = path[path.length - 1];\n\treturn physicalPort in portMap;\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 / logicalPortMapByHub - if specified, device must be in the map (hub map takes precedence when device has hub data)\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 / logicalPortMapByHub (if specified, device must be mapped)\n\tconst hasHubMap = config.logicalPortMapByHub && Object.keys(config.logicalPortMapByHub).length > 0;\n\tconst hasLocationMap = config.logicalPortMap && Object.keys(config.logicalPortMap).length > 0;\n\tif (hasHubMap && device.parentHubVid !== undefined && device.parentHubPid !== undefined && device.portPath && device.portPath.length > 0) {\n\t\tif (!isMappedInLogicalPortMapByHub(device, config)) {\n\t\t\treturn false;\n\t\t}\n\t} else if (hasLocationMap && config.logicalPortMap) {\n\t\tif (!(device.locationInfo in config.logicalPortMap)) {\n\t\t\treturn false;\n\t\t}\n\t} else if (hasHubMap) {\n\t\t// logicalPortMapByHub is set but device has no hub data - cannot be in map\n\t\treturn false;\n\t}\n\n\treturn true;\n}\n\n/**\n * Apply logical port mapping to a device if configured.\n * logicalPortMapByHub takes precedence when device has parent hub and port path.\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\tconst mapByHub = config.logicalPortMapByHub;\n\tif (\n\t\tmapByHub &&\n\t\tObject.keys(mapByHub).length > 0 &&\n\t\tdevice.parentHubVid !== undefined &&\n\t\tdevice.parentHubPid !== undefined &&\n\t\tdevice.portPath &&\n\t\tdevice.portPath.length > 0\n\t) {\n\t\tconst key = hubKeyFromParent(device.parentHubVid, device.parentHubPid);\n\t\tconst portMap = mapByHub[key];\n\t\tconst physicalPort = device.portPath[device.portPath.length - 1];\n\t\tif (portMap && physicalPort in portMap) {\n\t\t\treturn {\n\t\t\t\t...device,\n\t\t\t\tlogicalPort: portMap[physicalPort],\n\t\t\t};\n\t\t}\n\t}\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 type { DeviceInfo } from \"./types.js\";\n\n/**\n * Format device port path for display (e.g. \"2/3/1\" for port 2, then 3, then 1).\n * When portPath is available, returns slash-separated port numbers; otherwise returns locationInfo.\n *\n * @param device - Device info from the listener\n * @returns Port path string (e.g. \"2/3/1\") or locationInfo fallback\n */\nexport function formatPortPath(device: DeviceInfo): string {\n\tif (device.portPath && device.portPath.length > 0) {\n\t\treturn device.portPath.join(\"/\");\n\t}\n\treturn device.locationInfo;\n}\n"],
+  "mappings": "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",
+  "names": ["path", "require"]
 }

package/dist/types.d.ts

@@ -43,9 +43,22 @@ export interface DeviceInfo {
     locationInfo: string;
     /**
      * User-defined logical port number from configuration
-     * null if not mapped in logicalPortMap
+     * null if not mapped in logicalPortMap or logicalPortMapByHub
      */
     logicalPort: number | null;
+    /**
+     * Port path from root to device (e.g. [2, 3, 1] means port 2, then 3, then 1).
+     * Present when the native layer provides it (e.g. Windows); undefined or empty otherwise.
+     */
+    portPath?: number[];
+    /**
+     * VID of the hub the device is directly connected to (0 or undefined if on root).
+     */
+    parentHubVid?: number;
+    /**
+     * PID of the hub the device is directly connected to.
+     */
+    parentHubPid?: number;
 }
 /**
  * Target device filter by VID/PID
@@ -79,6 +92,18 @@ export interface ListenerConfig {
      * }
      */
     logicalPortMap?: Record<string, number>;
+    /**
+     * Map physical port to logical port per hub (alternative to logicalPortMap).
+     * Key: hub identifier "${vid}-${pid}" (hex, uppercase 4-char, e.g. "1A2C-3B4D").
+     * Value: map from physical port number to logical port number.
+     * When both logicalPortMap and logicalPortMapByHub could apply, logicalPortMapByHub takes precedence.
+     *
+     * @example
+     * {
+     *   "1A2C-3B4D": { 1: 4, 4: 2, 3: 3, 2: 1 }
+     * }
+     */
+    logicalPortMapByHub?: Record<string, Record<number, number>>;
     /**
      * Filter to monitor only specific devices by VID/PID
      *

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;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,kBAAkB;IAClC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAE7C;;;;;;;;OAQG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAE3C;;;;;;;;;;;OAWG;IACH,gBAAgB,IAAI,cAAc,CAAC;IAEnC;;;;;;;;;;;;;;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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;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;IAE3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;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,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE7D;;;;;;;;;;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,kBAAkB;IAClC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAE7C;;;;;;;;OAQG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAE3C;;;;;;;;;;;OAWG;IACH,gBAAgB,IAAI,cAAc,CAAC;IAEnC;;;;;;;;;;;;;;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"}

package/native/addon.cc

@@ -95,15 +95,22 @@ Napi::Value ListDevices(const Napi::CallbackInfo& info) {
 	
 	Napi::Array result = Napi::Array::New(env, devices.size());
 	for (size_t i = 0; i < devices.size(); i++) {
+		const DeviceInfo& d = devices[i];
 		Napi::Object obj = Napi::Object::New(env);
-		obj.Set("deviceId", Napi::String::New(env, devices[i].deviceId));
-		obj.Set("serialNumber", Napi::String::New(env, devices[i].serialNumber));
-		obj.Set("deviceName", Napi::String::New(env, devices[i].deviceName));
-		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));
-		// logicalPort is always null from native - it's set by JavaScript based on config
+		obj.Set("deviceId", Napi::String::New(env, d.deviceId));
+		obj.Set("serialNumber", Napi::String::New(env, d.serialNumber));
+		obj.Set("deviceName", Napi::String::New(env, d.deviceName));
+		obj.Set("vid", Napi::Number::New(env, d.vid));
+		obj.Set("pid", Napi::Number::New(env, d.pid));
+		obj.Set("locationInfo", Napi::String::New(env, d.locationInfo));
 		obj.Set("logicalPort", env.Null());
+		Napi::Array pathArr = Napi::Array::New(env, d.portPath.size());
+		for (size_t j = 0; j < d.portPath.size(); j++) {
+			pathArr[j] = Napi::Number::New(env, d.portPath[j]);
+		}
+		obj.Set("portPath", pathArr);
+		obj.Set("parentHubVid", Napi::Number::New(env, d.parentHubVid));
+		obj.Set("parentHubPid", Napi::Number::New(env, d.parentHubPid));
 		result[i] = obj;
 	}
 	

package/native/usb_listener_common.h

@@ -21,6 +21,9 @@ struct DeviceInfo {
 	uint16_t pid{0};            // Product ID
 	std::string locationInfo;   // Physical port location (platform-specific format)
 	int logicalPort{-1};        // User-defined logical port number (-1 if not mapped)
+	std::vector<int> portPath; // Port numbers from root to device (e.g. [2, 3, 1])
+	uint16_t parentHubVid{0};  // VID of hub device is directly connected to (0 if on root)
+	uint16_t parentHubPid{0};  // PID of that hub
 };
 
 /**

package/native/usb_listener_win.cc

@@ -197,6 +197,13 @@ void USBListener::HandleDeviceChange(WPARAM wParam, LPARAM lParam) {
 			} else {
 				obj.Set("logicalPort", env.Null());
 			}
+			Napi::Array pathArr = Napi::Array::New(env, data->portPath.size());
+			for (size_t j = 0; j < data->portPath.size(); j++) {
+				pathArr[j] = Napi::Number::New(env, data->portPath[j]);
+			}
+			obj.Set("portPath", pathArr);
+			obj.Set("parentHubVid", Napi::Number::New(env, data->parentHubVid));
+			obj.Set("parentHubPid", Napi::Number::New(env, data->parentHubPid));
 			jsCallback.Call({obj});
 			delete data;
 		};
@@ -215,6 +222,13 @@ void USBListener::HandleDeviceChange(WPARAM wParam, LPARAM lParam) {
 			} else {
 				obj.Set("logicalPort", env.Null());
 			}
+			Napi::Array pathArr = Napi::Array::New(env, data->portPath.size());
+			for (size_t j = 0; j < data->portPath.size(); j++) {
+				pathArr[j] = Napi::Number::New(env, data->portPath[j]);
+			}
+			obj.Set("portPath", pathArr);
+			obj.Set("parentHubVid", Napi::Number::New(env, data->parentHubVid));
+			obj.Set("parentHubPid", Napi::Number::New(env, data->parentHubPid));
 			jsCallback.Call({obj});
 			delete data;
 		};
@@ -325,6 +339,7 @@ bool USBListener::GetDeviceInfo(const std::string& devicePath, DeviceInfo& info)
 				// Get device name
 				info.deviceName = GetDeviceName(deviceInfoSet, devInfoData);
 				
+				FillPortPathAndParentHub(devInst, info);
 				SetupDiDestroyDeviceInfoList(deviceInfoSet);
 				return true;
 			}
@@ -349,6 +364,87 @@ bool USBListener::GetLocationInfo(DEVINST devInst, std::string& locationInfo) {
 	return true;
 }
 
+/**
+ * Parse port number from Windows location string.
+ * Supports "Port_#0005.Hub_#0002" (returns 5) and dot-separated format (last non-zero segment).
+ */
+bool USBListener::ParsePortFromLocation(const std::string& locationInfo, int& port) {
+	if (locationInfo.empty()) {
+		return false;
+	}
+	// Format: Port_#0005.Hub_#0002 or Port_#0005
+	size_t pos = locationInfo.find("Port_#");
+	if (pos != std::string::npos) {
+		pos += 6;  // length of "Port_#"
+		size_t end = pos;
+		while (end < locationInfo.size() && (std::isxdigit(static_cast<unsigned char>(locationInfo[end])) || locationInfo[end] == '.')) {
+			if (locationInfo[end] == '.') break;
+			++end;
+		}
+		if (end > pos) {
+			try {
+				port = std::stoi(locationInfo.substr(pos, end - pos), nullptr, 10);
+				return true;
+			} catch (...) {
+				// fall through to dot-separated
+			}
+		}
+	}
+	// Dot-separated format (e.g. 0000.001a.0000.001.003)
+	size_t last = locationInfo.rfind('.');
+	std::string segment = (last != std::string::npos && last + 1 < locationInfo.size())
+		? locationInfo.substr(last + 1) : locationInfo;
+	if (!segment.empty()) {
+		try {
+			port = std::stoi(segment, nullptr, 10);
+			return true;
+		} catch (...) {}
+	}
+	return false;
+}
+
+/**
+ * Walk device tree from device to root, collect port numbers, set portPath (root-to-device) and parent hub VID/PID.
+ */
+void USBListener::FillPortPathAndParentHub(DEVINST devInst, DeviceInfo& info) {
+	info.portPath.clear();
+	info.parentHubVid = 0;
+	info.parentHubPid = 0;
+	std::vector<int> pathDeviceToRoot;
+	DEVINST current = devInst;
+	bool firstParent = true;
+	for (;;) {
+		std::string location;
+		if (!GetLocationInfo(current, location)) {
+			break;
+		}
+		int portNum = 0;
+		if (ParsePortFromLocation(location, portNum)) {
+			pathDeviceToRoot.push_back(portNum);
+		}
+		DEVINST parentInst = 0;
+		CONFIGRET cr = CM_Get_Parent(&parentInst, current, 0);
+		if (cr != CR_SUCCESS || parentInst == 0 || parentInst == current) {
+			break;
+		}
+		if (firstParent) {
+			firstParent = false;
+			WCHAR deviceIdBuffer[256];
+			deviceIdBuffer[0] = 0;
+			if (CM_Get_Device_IDW(parentInst, deviceIdBuffer, 256, 0) == CR_SUCCESS) {
+				std::wstring idW = deviceIdBuffer;
+				std::string parentId(idW.begin(), idW.end());
+				GetVidPid(parentId, info.parentHubVid, info.parentHubPid);
+			}
+		}
+		current = parentInst;
+	}
+	// Reverse so portPath is root-to-device
+	for (auto it = pathDeviceToRoot.rbegin(); it != pathDeviceToRoot.rend(); ++it) {
+		info.portPath.push_back(*it);
+	}
+}
+
 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_");
@@ -451,6 +547,7 @@ void USBListener::EnumerateConnectedDevices() {
 			// Get device name
 			info.deviceName = GetDeviceName(deviceInfoSet, devInfoData);
 			
+			FillPortPathAndParentHub(devInst, info);
 			// Cache device with exclusive lock
 			{
 				std::unique_lock lock(m_cacheMutex);
@@ -471,6 +568,13 @@ void USBListener::EnumerateConnectedDevices() {
 					} else {
 						obj.Set("logicalPort", env.Null());
 					}
+					Napi::Array pathArr = Napi::Array::New(env, data->portPath.size());
+					for (size_t j = 0; j < data->portPath.size(); j++) {
+						pathArr[j] = Napi::Number::New(env, data->portPath[j]);
+					}
+					obj.Set("portPath", pathArr);
+					obj.Set("parentHubVid", Napi::Number::New(env, data->parentHubVid));
+					obj.Set("parentHubPid", Napi::Number::New(env, data->parentHubPid));
 					jsCallback.Call({obj});
 					delete data;
 				};
@@ -520,6 +624,7 @@ std::vector<DeviceInfo> USBListener::ListAllDevices() {
 			// Get device name
 			info.deviceName = GetDeviceName(deviceInfoSet, devInfoData);
 			
+			FillPortPathAndParentHub(devInst, info);
 			devices.push_back(info);
 		}
 	}

package/native/usb_listener_win.h

@@ -74,6 +74,8 @@ private:
 	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 ParsePortFromLocation(const std::string& locationInfo, int& port);    // Parse port number from location string
+	void FillPortPathAndParentHub(DEVINST devInst, DeviceInfo& info);          // Walk device tree, set portPath and parentHubVid/Pid
 	std::string GetSerialNumber(HDEVINFO deviceInfoSet, SP_DEVINFO_DATA& devInfoData); // Get USB serial number
 	std::string GetDeviceName(HDEVINFO deviceInfoSet, SP_DEVINFO_DATA& devInfoData);   // Get device description/name
 	bool GetVidPid(const std::string& deviceId, uint16_t& vid, uint16_t& pid); // Parse VID/PID from device ID string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcesystems/usb-device-listener",
-  "version": "1.0.76",
+  "version": "1.0.78",
   "description": "Native cross-platform USB device listener for Windows and macOS",
   "main": "dist/index.js",
   "module": "dist/index.mjs",