@ecobridge.xyz/devicemanager 3.0.2 → 3.1.1

package/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Task Venture Capital GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecobridge.xyz/devicemanager",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "private": false,
   "description": "a device manager for talking to devices on network and over usb",
   "main": "dist_ts/index.js",
@@ -8,32 +8,23 @@
   "type": "module",
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
+  "devDependencies": {
+    "@git.zone/tsbuild": "4.4.2",
+    "@git.zone/tsrun": "2.0.6",
+    "@git.zone/tstest": "4.0.0",
+    "@types/node": "26.2.0",
+    "@types/ws": "8.18.1"
+  },
+  "dependencies": {
+    "@push.rocks/smartdelay": "3.1.0",
+    "@push.rocks/smartpath": "6.0.0",
+    "bonjour-service": "1.4.4",
+    "net-snmp": "3.26.3",
+    "ws": "8.21.1"
+  },
   "scripts": {
     "test": "(tstest test/ --verbose)",
     "build": "(tsbuild --web --allowimplicitany)",
     "buildDocs": "(tsdoc)"
-  },
-  "devDependencies": {
-    "@git.zone/tsbuild": "^4.1.0",
-    "@git.zone/tsrun": "^2.0.0",
-    "@git.zone/tstest": "^3.1.3",
-    "@types/node": "^25.0.3",
-    "@types/ws": "^8.18.1"
-  },
-  "dependencies": {
-    "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartevent": "^2.0.5",
-    "@push.rocks/smartnetwork": "^4.4.0",
-    "@push.rocks/smartpath": "^6.0.0",
-    "@push.rocks/smartpromise": "^4.2.3",
-    "@push.rocks/smartrequest": "^5.0.1",
-    "@push.rocks/smartxml": "^2.0.0",
-    "bonjour-service": "^1.3.0",
-    "castv2-client": "^1.2.0",
-    "ipp": "^2.0.1",
-    "net-snmp": "^3.26.0",
-    "node-ssdp": "^4.0.1",
-    "sonos": "^1.14.2",
-    "ws": "^8.19.0"
   }
-}
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+allowBuilds:
+  esbuild: true
+  mongodb-memory-server: false
+  puppeteer: false

package/readme.md

@@ -7,14 +7,14 @@ A comprehensive, TypeScript-first device manager for discovering and communicati
 
 ## 🎯 Overview
 
-`@ecobridge.xyz/devicemanager` provides a unified, object-oriented API for discovering and controlling network devices. Whether you're building a document scanning workflow, managing printers, controlling smart home devices, or monitoring UPS systems — this library has you covered.
+`@ecobridge.xyz/devicemanager` provides a unified, object-oriented API for discovering and modeling network devices, with live communication where protocol implementations are available. Whether you're building a document scanning workflow, managing printers, controlling smart home devices, or monitoring UPS systems — this library has you covered.
 
 **Supported Device Types:**
 - 🖨️ **Scanners** — eSCL (AirScan), SANE protocols
-- 📄 **Printers** — IPP, JetDirect protocols
-- 🔊 **Speakers** — Sonos, AirPlay, Chromecast, DLNA
+- 📄 **Printers** — IPP discovery and print execution; JetDirect/raw port detection
+- 🔊 **Speakers** — Sonos, AirPlay, Chromecast, and DLNA discovery with normalized feature/factory modeling
 - 🔋 **UPS Systems** — NUT, SNMP protocols
-- 📡 **SNMP Devices** — Generic SNMP v1/v2c/v3 support
+- 📡 **SNMP Devices** — Community-based SNMP v1 and v2c sessions; v3 is not implemented
 - 🏠 **Smart Home** — Home Assistant integration (lights, switches, sensors, climate, locks, fans, cameras, covers)
 
 ## Issue Reporting and Security
@@ -119,13 +119,14 @@ The central orchestrator for device discovery and management.
 
 ```typescript
 const manager = new DeviceManager({
-  autoDiscovery: true,      // Enable mDNS/SSDP auto-discovery
   discoveryTimeout: 10000,  // Discovery timeout in ms
   enableRetry: true,        // Enable retry with exponential backoff
   maxRetries: 5,            // Maximum retry attempts
 });
 ```
 
+Constructing `DeviceManager` does not initiate network discovery. Call `startDiscovery()` explicitly when continuous mDNS/SSDP discovery should begin; the `autoDiscovery` option does not currently trigger startup.
+
 #### Discovery Methods
 
 ```typescript
@@ -240,6 +241,8 @@ await fs.writeFile('scan.jpg', result.data);
 
 #### 📄 PrintFeature
 
+`PrintFeature.print()` submits jobs through IPP. Network discovery can identify an open JetDirect/raw port at TCP 9100, but JetDirect print execution is not implemented.
+
 ```typescript
 const printFeature = device.selectFeature<PrintFeature>('print');
 await printFeature.connect();
@@ -257,31 +260,33 @@ const job = await printFeature.print(pdfBuffer, {
   jobName: 'My Document',
 });
 
-// Check job status
-const status = await printFeature.getJobStatus(job.id);
+// Get current job information
+const jobInfo = await printFeature.getJobInfo(job.id);
 ```
 
 #### 🔊 PlaybackFeature & VolumeFeature
 
+`PlaybackFeature` and `VolumeFeature` provide normalized capability and state models. No external Sonos or Chromecast protocol client is bundled or wired into these features, so their methods update local feature state and emit events but do not provide live playback control for those devices.
+
 ```typescript
 const playback = device.selectFeature<PlaybackFeature>('playback');
 const volume = device.selectFeature<VolumeFeature>('volume');
 await playback.connect();
 
-// Control playback
+// Update normalized playback state
 await playback.play('http://example.com/audio.mp3');
 await playback.pause();
 await playback.stop();
 await playback.seek(120); // seconds
 
-// Get playback status
-const status = await playback.getStatus();
-// { state: 'playing', position: 45, duration: 180, track: { title: '...' } }
+// Get normalized playback status
+const status = await playback.getPlaybackStatus();
+// { state: 'stopped', position: 120, duration: 0, track: undefined }
 
-// Control volume
+// Update normalized volume state
 await volume.setVolume(50);    // 0-100
-await volume.mute();
-await volume.unmute();
+await volume.setMute(true);
+await volume.toggleMute();
 const level = await volume.getVolume();
 ```
 
@@ -293,14 +298,16 @@ await power.connect();
 
 // Get UPS status
 const status = await power.getStatus();
-// { status: 'online', battery: { charge: 100, runtime: 1800, voltage: 13.8 }, ... }
+// 'online' | 'onbattery' | 'lowbattery' | ... | 'unknown'
 
 // Get battery info
 const battery = await power.getBatteryInfo();
-// { charge: 95, runtime: 1500, health: 'good' }
+// { charge: 0, runtime: 0 } until a protocol-specific implementation updates it
 
-// Run self-test
-await power.runTest();
+// Run a battery test when supported
+if (power.supportsTest) {
+  await power.testBattery();
+}
 ```
 
 #### 🏠 Smart Home Features
@@ -309,9 +316,9 @@ await power.runTest();
 // Light control
 const light = device.selectFeature<LightFeature>('light');
 await light.turnOn();
-await light.setBrightness(80);
-await light.setColor({ r: 255, g: 100, b: 50 });
-await light.setColorTemperature(4000); // Kelvin
+await light.setBrightness(80); // 0-255
+await light.setRgbColor(255, 100, 50);
+await light.setColorTemp(4000); // Kelvin
 
 // Switch control
 const switch_ = device.selectFeature<SwitchFeature>('switch');
@@ -321,13 +328,16 @@ await switch_.toggle();
 
 // Climate control
 const climate = device.selectFeature<ClimateFeature>('climate');
-await climate.setTargetTemperature(22);
-await climate.setMode('heat'); // 'heat' | 'cool' | 'auto' | 'off'
+await climate.setTargetTemp(22);
+await climate.setHvacMode('heat'); // 'heat' | 'cool' | 'auto' | 'off'
 
 // Sensor reading
 const sensor = device.selectFeature<SensorFeature>('sensor');
-const reading = await sensor.getState();
-// { temperature: 22.5, humidity: 45, battery: 85 }
+const reading = await sensor.refreshState();
+// { value: 22.5, numericValue: 22.5, unit: '°C', lastUpdated: Date }
+
+// Cached accessors reflect the most recently fetched or externally updated state
+console.log(sensor.value, sensor.numericValue, sensor.unit, sensor.lastUpdated);
 ```
 
 ### Protocol Direct Access
@@ -343,7 +353,7 @@ const caps = await escl.getCapabilities();
 const result = await escl.scan({ source: 'flatbed', resolution: 300 });
 
 // Direct IPP access
-const ipp = new IppProtocol('ipp://192.168.1.100:631/ipp/print');
+const ipp = new IppProtocol('192.168.1.100', 631, '/ipp/print');
 const printerAttrs = await ipp.getPrinterAttributes();
 
 // Direct SNMP access
@@ -360,7 +370,7 @@ import { HomeAssistantProtocol, HomeAssistantDiscovery } from '@ecobridge.xyz/de
 const ha = new HomeAssistantProtocol({
   host: 'homeassistant.local',
   port: 8123,
-  accessToken: 'your_long_lived_access_token',
+  token: 'your_long_lived_access_token',
 });
 
 await ha.connect();
@@ -369,22 +379,25 @@ await ha.connect();
 const entities = await ha.getStates();
 
 // Control a light
-await ha.callService('light', 'turn_on', {
-  entity_id: 'light.living_room',
-  brightness: 200,
-});
+await ha.callService(
+  'light',
+  'turn_on',
+  { entity_id: 'light.living_room' },
+  { brightness: 200 }
+);
 
 // Subscribe to state changes
-ha.on('state_changed', (event) => {
-  console.log(`${event.entity_id}: ${event.new_state.state}`);
+await ha.subscribeToStateChanges();
+ha.on('state:changed', (event) => {
+  console.log(`${event.entity_id}: ${event.new_state?.state ?? 'removed'}`);
 });
 
 // Auto-discover Home Assistant instances via mDNS
 const discovery = new HomeAssistantDiscovery();
-discovery.on('found', (instance) => {
-  console.log(`Found HA at ${instance.address}:${instance.port}`);
+discovery.on('instance:found', (instance) => {
+  console.log(`Found HA at ${instance.host}:${instance.port}`);
 });
-await discovery.start();
+await discovery.startMdnsDiscovery();
 ```
 
 ### Helper Utilities
@@ -405,7 +418,7 @@ const result = await withRetry(
 
 // IP utilities
 isValidIp('192.168.1.1');           // true
-cidrToIps('192.168.1.0/30');        // ['192.168.1.0', '192.168.1.1', ...]
+cidrToIps('192.168.1.0/30');        // ['192.168.1.1', '192.168.1.2']
 getLocalSubnet();                    // '192.168.1.0/24'
 ```
 
@@ -425,8 +438,8 @@ The library supports multiple discovery mechanisms:
 ```typescript
 import { SERVICE_TYPES } from '@ecobridge.xyz/devicemanager';
 
-// Available: escl, ipp, ipp-tls, airplay, raop,
-// googlecast, sonos, sane, http, https, printer
+// Keys: ESCL, ESCL_SECURE, SANE, IPP, IPPS, PDL,
+// AIRPLAY, RAOP, SONOS, GOOGLECAST, SPOTIFY
 ```
 
 ### SSDP Service Types
@@ -434,11 +447,12 @@ import { SERVICE_TYPES } from '@ecobridge.xyz/devicemanager';
 ```typescript
 import { SSDP_SERVICE_TYPES } from '@ecobridge.xyz/devicemanager';
 
-// Available: all, rootdevice, mediaRenderer, mediaServer,
-// contentDirectory, avtransport, renderingControl,
-// connectionManager, zonePlayer
+// Root, DLNA media renderer/server, Sonos ZonePlayer,
+// UPnP basic device and internet gateway service types
 ```
 
+`SsdpDiscovery` uses native UDP sockets bound to every non-internal IPv4 interface. Searches are repeated every 30 seconds, and `search(serviceType)` can send an additional focused M-SEARCH while discovery is running. `start()` and `stop()` are idempotent and release all sockets, timers, and pending description requests.
+
 ## 🎯 Feature Types
 
 ```typescript
@@ -492,7 +506,7 @@ const printer = createPrinter({
   txtRecords: { rp: '/ipp/print' },
 });
 
-// Create a Sonos speaker
+// Create a normalized Sonos speaker model (no live protocol client is created)
 const speaker = createSpeaker({
   id: 'living-room-sonos',
   name: 'Living Room',
@@ -504,34 +518,7 @@ const speaker = createSpeaker({
 
 ### Smart Home Factory Functions
 
-```typescript
-import {
-  createSmartLight,
-  createSmartSwitch,
-  createSmartSensor,
-  createSmartClimate,
-  createSmartCover,
-  createSmartLock,
-  createSmartFan,
-  createSmartCamera,
-} from '@ecobridge.xyz/devicemanager';
-
-// Create devices with Home Assistant integration
-const light = createSmartLight({
-  id: 'living-room-light',
-  name: 'Living Room Light',
-  address: 'homeassistant.local',
-  port: 8123,
-  entityId: 'light.living_room',
-  protocol: 'home-assistant',
-  protocolClient: haClient,  // Your HomeAssistantProtocol instance
-  capabilities: {
-    supportsBrightness: true,
-    supportsColorTemp: true,
-    supportsRgb: true,
-  },
-});
-```
+The smart-home factories require a `protocolClient` that implements the corresponding feature interface, such as `ILightProtocolClient` for `createSmartLight()`. `HomeAssistantProtocol` exposes Home Assistant-specific service methods and entity state shapes, so it cannot be passed directly as that client; use a protocol adapter that implements the required interface.
 
 ### Event Handling
 
@@ -596,15 +583,13 @@ const maybePrint = device.getFeature<PrintFeature>('print'); // undefined
 
 Built with ❤️ using:
 - [bonjour-service](https://github.com/onlxltd/bonjour-service) - mDNS discovery
-- [node-ssdp](https://github.com/diversario/node-ssdp) - SSDP/UPnP discovery
+- [Node.js networking and fetch APIs](https://nodejs.org/api/) - SSDP, IPP, eSCL, UPnP, and active network discovery
 - [net-snmp](https://github.com/markabrahams/node-net-snmp) - SNMP protocol
-- [ipp](https://github.com/niclaslindstedt/ipp) - IPP printing protocol
-- [sonos](https://github.com/bencevans/node-sonos) - Sonos control
-- [castv2-client](https://github.com/thibauts/node-castv2-client) - Chromecast protocol
+- [ws](https://github.com/websockets/ws) - Home Assistant WebSocket transport
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license.md](./license.md) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

package/test/{test.ts → test.node.ts}

@@ -127,50 +127,6 @@ tap.test('withRetry should throw after max retries', async () => {
   expect(callCount).toEqual(3); // Initial + 2 retries
 });
 
-// Test discovery (non-blocking)
-tap.test('should start and stop discovery', async () => {
-  const dm = new devicemanager.DeviceManager();
-
-  // Track events
-  let discoveryStarted = false;
-  let discoveryStopped = false;
-
-  dm.on('discovery:started', () => {
-    discoveryStarted = true;
-  });
-
-  dm.on('discovery:stopped', () => {
-    discoveryStopped = true;
-  });
-
-  await dm.startDiscovery();
-  expect(dm.isDiscovering).toEqual(true);
-  expect(discoveryStarted).toEqual(true);
-
-  // Wait a bit for potential device discovery
-  await new Promise((resolve) => setTimeout(resolve, 2000));
-
-  // Log discovered devices using new API
-  const scanners = dm.getDevices({ hasFeature: 'scan' });
-  const printers = dm.getDevices({ hasFeature: 'print' });
-  console.log(`Discovered ${scanners.length} scanner(s) and ${printers.length} printer(s)`);
-
-  for (const scanner of scanners) {
-    const scanFeature = scanner.getFeature<devicemanager.ScanFeature>('scan');
-    console.log(`  Scanner: ${scanner.name} (${scanner.address}) - ${scanFeature?.protocol || 'unknown'}`);
-  }
-
-  for (const printer of printers) {
-    console.log(`  Printer: ${printer.name} (${printer.address})`);
-  }
-
-  await dm.stopDiscovery();
-  expect(dm.isDiscovering).toEqual(false);
-  expect(discoveryStopped).toEqual(true);
-
-  await dm.shutdown();
-});
-
 // Test Scanner creation using factory
 tap.test('should create Scanner device using factory', async () => {
   const scanner = devicemanager.createScanner({
@@ -204,8 +160,8 @@ tap.test('should create Printer device using factory', async () => {
     name: 'Test Printer',
     address: '192.168.1.101',
     port: 631,
-    ippPath: '/ipp/print',
     txtRecords: {
+      'rp': '/ipp/print',
       'ty': 'Brother HL-L2350DW',
       'Color': 'T',
       'Duplex': 'T',
@@ -221,6 +177,25 @@ tap.test('should create Printer device using factory', async () => {
   expect(printFeature).toBeInstanceOf(devicemanager.PrintFeature);
 });
 
+tap.test('should create a Sonos speaker without an external Sonos client', async () => {
+  const speaker = devicemanager.createSpeaker({
+    id: 'test:speaker:sonos',
+    name: 'Living Room',
+    address: '192.168.1.102',
+    port: 1400,
+    protocol: 'sonos',
+  });
+
+  const playback = speaker.selectFeature<devicemanager.PlaybackFeature>('playback');
+  const volume = speaker.selectFeature<devicemanager.VolumeFeature>('volume');
+
+  expect(speaker.id).toEqual('test:speaker:sonos');
+  expect(playback.protocol).toEqual('sonos');
+  expect(playback.supportsQueue).toEqual(true);
+  expect(playback.supportsSeek).toEqual(true);
+  expect(volume.protocol).toEqual('sonos');
+});
+
 // Test UniversalDevice feature management
 tap.test('should manage features on UniversalDevice', async () => {
   const device = new devicemanager.UniversalDevice('192.168.1.50', 80, {