@ecobridge.xyz/devicemanager 3.1.0 → 3.2.0

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@ecobridge.xyz/devicemanager",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "private": false,
   "description": "a device manager for talking to devices on network and over usb",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
+  "packageManager": "pnpm@11.21.0",
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "scripts": {
@@ -14,26 +15,20 @@
     "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"
+    "@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.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"
+    "@push.rocks/smartdelay": "3.1.0",
+    "@push.rocks/smartpath": "6.0.0",
+    "@push.rocks/smartsamba": "0.3.1",
+    "bonjour-service": "1.4.4",
+    "fast-xml-parser": "4.5.7",
+    "net-snmp": "3.26.3",
+    "rxjs": "7.8.2",
+    "ws": "8.21.1"
   }
 }

package/pnpm-workspace.yaml

@@ -0,0 +1,6 @@
+allowBuilds:
+  esbuild: true
+  mongodb-memory-server: false
+  puppeteer: false
+minimumReleaseAgeExclude:
+  - '@push.rocks/smartsamba@0.3.1'

package/readme.md

@@ -7,14 +7,15 @@ 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
+- 🖨️ **Scanners** — Brother native network scanning, eSCL (AirScan), and SANE
+- 📄 **Printers** — IPP/AirPrint discovery, capabilities, jobs, cancellation, and print execution; JetDirect/raw port detection
+- 📁 **SMB Shares** — Host local folders through smartsamba and emit settled document arrivals through RxJS
+- 🔊 **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
@@ -107,7 +108,7 @@ The library follows a clean, composable architecture:
                               ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                        Protocols                            │
-│  eSCL │ SANE │ IPP │ SNMP │ NUT │ UPnP/SOAP │ Home Assistant│
+│ Brother Scan │ eSCL │ SANE │ IPP │ SNMP │ NUT │ UPnP/SOAP  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -119,13 +120,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
@@ -141,6 +143,7 @@ const printers = await manager.discoverPrinters('192.168.1.0/24');
 // General network scan (all device types)
 const devices = await manager.scanNetwork({
   ipRange: '192.168.1.0/24',
+  probeBrother: true,
   probeEscl: true,
   probeIpp: true,
   probeSane: true,
@@ -236,16 +239,46 @@ const result = await scanFeature.scan({
 
 // result.data is a Buffer containing the scanned image
 await fs.writeFile('scan.jpg', result.data);
+
+// ADF scans expose every returned document. `data` remains the first document
+// for backwards compatibility. Use `pages` to avoid dropping later sheets/sides.
+console.log(`Scanner returned ${result.pageCount} document(s)`);
+for (const [index, page] of (result.pages ?? []).entries()) {
+  await fs.writeFile(`scan-${index + 1}.jpg`, page.data);
+}
 ```
 
+If a scanner times out or cancels after transferring one or more documents,
+`EsclScanError.partialResult` contains those documents with `isComplete: false`.
+Callers can persist `partialResult.pages` before deciding whether to retry.
+Some scanner firmware accepts eSCL settings but returns a different format or
+resolution. Check `result.settingsWarnings` before treating the requested scan
+quality as confirmed.
+
+Brother devices discovered on TCP 54921 use the native scan transport before
+eSCL. It explicitly selects `AUTO` for ADF input, controls simplex/duplex, and
+rejects a lease when the device does not grant the requested resolution. The
+native transport currently returns color JPEG pages; unsupported output formats
+or color modes fail explicitly instead of being silently substituted.
+Duplex-capable scanners default to `adf-duplex`; callers can still request
+`adf` or `flatbed` explicitly. The transport preserves every returned side.
+Blank-page classification and removal belong in consuming applications, where
+document-specific review rules can be applied.
+
 #### 📄 PrintFeature
 
+`PrintFeature.print()` submits jobs through IPP, the print transport used by
+AirPrint. It reads printer capabilities, submits jobs, reports job state, and
+supports cancellation. Network discovery can also 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();
 
 // Get printer capabilities
 const caps = await printFeature.getCapabilities();
+console.log(caps.airPrintSupported, caps.documentFormats, caps.resolutions);
 
 // Print a document
 const job = await printFeature.print(pdfBuffer, {
@@ -257,31 +290,87 @@ 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);
+```
+
+#### 📁 SMB Share Provider
+
+`DeviceManager.provideSmbShares()` hosts one or more local folders with
+`@push.rocks/smartsamba`. The provider waits until a new file has stopped
+changing before it emits `document:arrived`, which keeps consumers from opening
+a scan while the sending device is still writing it.
+
+```typescript
+import { DeviceManager } from '@ecobridge.xyz/devicemanager';
+
+const manager = new DeviceManager({ autoDiscovery: false });
+const provider = await manager.provideSmbShares({
+  host: '0.0.0.0',
+  port: 445,
+  users: [{
+    username: 'scanner',
+    password: process.env.SMB_SCANNER_PASSWORD!,
+  }],
+  shares: [{
+    name: 'scans',
+    path: '/srv/device-scans',
+    users: [{ username: 'scanner', access: 'readWrite' }],
+  }],
+  settleTimeMs: 1000,
+});
+
+const subscription = provider.documents$.subscribe((document) => {
+  console.log(`New document: ${document.shareName}/${document.relativePath}`);
+});
+
+// The same event is forwarded through the manager as smb:document:arrived.
+const managerSubscription = manager.events$.subscribe((event) => {
+  if (event.name === 'smb:document:arrived') {
+    console.log(event.args[0]);
+  }
+});
+
+// Later:
+subscription.unsubscribe();
+managerSubscription.unsubscribe();
+await manager.shutdown();
 ```
 
+The provider recursively monitors every configured share. It also emits
+`document:changed`, `document:removed`, `started`, `stopped`, and
+`provider:error`. Existing files are treated as the startup baseline unless
+`emitExistingDocuments` is enabled.
+
+Binding SMB's standard TCP port 445 can require elevated privileges. Published
+smartsamba 0.3.1 packages support signed SMB 2.0.2 and 2.1 clients and include
+Linux amd64 and arm64 engines. Other platforms can provide a locally built engine
+through `SMARTSAMBA_RUST_BINARY`.
+Do not store SMB passwords in device metadata or log provider options.
+
 #### 🔊 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 +382,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 +400,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 +412,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 +437,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 +454,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 +463,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 +502,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 +522,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 +531,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 +590,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,40 +602,21 @@ 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
 
+`DeviceManager`, `UniversalDevice`, every `Feature`, and host-side providers
+remain Node `EventEmitter` instances and additionally expose `events$`. Each
+observable item contains the event `name`, its `args`, and `emittedAt`.
+
 ```typescript
 const manager = new DeviceManager();
 
+const subscription = manager.events$.subscribe((event) => {
+  console.log(event.name, event.args, event.emittedAt);
+});
+
 // Discovery events
 manager.on('device:found', ({ device, featureType }) => {
   console.log(`Found ${device.name} with ${featureType} capability`);
@@ -560,6 +639,8 @@ device.on('status:changed', ({ oldStatus, newStatus }) => {
 device.on('feature:connected', (featureType) => {
   console.log(`Feature ${featureType} connected`);
 });
+
+subscription.unsubscribe();
 ```
 
 ### Error Handling
@@ -596,15 +677,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.