v3.0.2

changelog.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2026-01-12 - 3.0.2 - fix(devicemanager)
+no changes detected - nothing to commit
+
+- git diff indicates no modifications, additions, or deletions
+- no files were changed in the provided diff
+
+## 2026-01-12 - 3.0.1 - fix(release)
+add npm registries to release config and expand documentation for UniversalDevice architecture and smart-home features
+
+- npmextra.json: add "registries" to release configuration to publish to both Verdaccio (https://verdaccio.lossless.digital) and the npm registry
+- readme.hints.md: rewritten/expanded implementation notes to describe the UniversalDevice architecture, composable features (including smart-home types like light, switch, sensor, climate, cover, lock, fan, camera), protocols, discovery, factories, interfaces, and testing guidance
+- readme.md: add factory usage examples including smart-home factory functions, update txtRecords usage (rp) in examples, and small copy/emoji edits
+
 ## 2026-01-10 - 3.0.0 - BREAKING CHANGE(devicemanager)
 migrate tests to new UniversalDevice/feature-based API, add device factories, SNMP protocol/feature and IP helper utilities
 

npmextra.json

@@ -11,7 +11,11 @@
       "projectDomain": "ecobridge.xyz"
     },
     "release": {
-      "accessLevel": "public"
+      "accessLevel": "public",
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ]
     }
   },
   "@ship.zone/szci": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecobridge.xyz/devicemanager",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "private": false,
   "description": "a device manager for talking to devices on network and over usb",
   "main": "dist_ts/index.js",

readme.hints.md

@@ -2,20 +2,20 @@
 
 ## Architecture Overview
 
-The device manager supports two architectures:
+The device manager uses a **UniversalDevice** architecture with composable features.
 
-### Legacy Architecture (Still Supported)
+### Key Concepts
-- Separate device classes: `Scanner`, `Printer`, `Speaker`, `SnmpDevice`, `UpsDevice`, `DlnaRenderer`, `DlnaServer`
-- Type-specific collections in DeviceManager
-- Type-based queries: `getScanners()`, `getPrinters()`, `getSpeakers()`
 
-### New Universal Device Architecture
+- **UniversalDevice**: A single device class that can have multiple features attached
-- Single `UniversalDevice` class with composable features
+- **Features**: Composable capabilities (scan, print, playback, volume, power, snmp, smart home, etc.)
-- Features are capabilities that can be attached to any device
+- **Protocols**: Low-level protocol implementations (eSCL, SANE, IPP, SNMP, NUT, UPnP, Home Assistant)
-- Supports multifunction devices naturally (e.g., printer+scanner)
 
 ## Key Files
 
+### Core (`ts/`)
+- `devicemanager.classes.devicemanager.ts` - Main DeviceManager class with discovery and device registry
+- `device/device.classes.device.ts` - UniversalDevice class with feature management
+
 ### Features (`ts/features/`)
 - `feature.abstract.ts` - Base Feature class with connection management and retry logic
 - `feature.scan.ts` - Scanning via eSCL/SANE protocols
@@ -24,43 +24,92 @@ The device manager supports two architectures:
 - `feature.volume.ts` - Volume control (separate from playback)
 - `feature.power.ts` - UPS/power monitoring via NUT/SNMP
 - `feature.snmp.ts` - SNMP queries
+- `feature.light.ts` - Smart light control
+- `feature.switch.ts` - Smart switch control
+- `feature.sensor.ts` - Smart sensors
+- `feature.climate.ts` - Climate/HVAC control
+- `feature.cover.ts` - Blinds, garage doors
+- `feature.lock.ts` - Smart locks
+- `feature.fan.ts` - Fan control
+- `feature.camera.ts` - Camera control
 
-### Device (`ts/device/`)
+### Protocols (`ts/protocols/`)
-- `device.classes.device.ts` - UniversalDevice class with feature management
+- `protocol.escl.ts` - eSCL/AirScan scanner protocol
+- `protocol.sane.ts` - SANE network scanner protocol
+- `protocol.ipp.ts` - IPP printer protocol
+- `protocol.snmp.ts` - SNMP queries
+- `protocol.nut.ts` - Network UPS Tools protocol
+- `protocol.upnp.ts` - UPnP/SOAP client
+- `protocol.upssnmp.ts` - UPS-specific SNMP
+- `protocol.homeassistant.ts` - Home Assistant WebSocket API
+
+### Discovery (`ts/discovery/`)
+- `discovery.classes.mdns.ts` - mDNS discovery (Bonjour)
+- `discovery.classes.ssdp.ts` - SSDP/UPnP discovery
+- `discovery.classes.networkscanner.ts` - Active network scanning
+- `discovery.classes.homeassistant.ts` - Home Assistant instance discovery
+
+### Factories (`ts/factories/`)
+- `index.ts` - Device factory functions for creating pre-configured devices:
+  - `createScanner`, `createPrinter`, `createSpeaker`, `createDlnaRenderer`
+  - `createSnmpDevice`, `createUpsDevice`
+  - Smart home: `createSmartLight`, `createSmartSwitch`, `createSmartSensor`, etc.
 
 ### Interfaces (`ts/interfaces/`)
 - `feature.interfaces.ts` - All feature-related types and interfaces
-- `index.ts` - Re-exports feature interfaces
+- `smarthome.interfaces.ts` - Smart home specific interfaces
+- `homeassistant.interfaces.ts` - Home Assistant API types
+- `index.ts` - Re-exports all interfaces
 
 ## Feature Types
+
 ```typescript
 type TFeatureType =
   | 'scan' | 'print' | 'fax' | 'copy'
   | 'playback' | 'volume' | 'power' | 'snmp'
-  | 'dlna-render' | 'dlna-serve';
+  | 'dlna-render' | 'dlna-serve'
+  | 'light' | 'climate' | 'sensor' | 'camera'
+  | 'cover' | 'switch' | 'lock' | 'fan';
 ```
 
-## DeviceManager Feature API
+## DeviceManager API
+
 ```typescript
 // Query by features
-dm.getDevicesWithFeature('scan');           // Devices with scan feature
+dm.getDevices();                              // All devices
+dm.getDevices({ hasFeature: 'scan' });        // Devices with scan feature
+dm.getDevices({ name: 'Brother' });           // Devices matching name
 dm.getDevicesWithFeatures(['scan', 'print']); // Devices with ALL features
 dm.getDevicesWithAnyFeature(['playback', 'volume']); // Devices with ANY feature
 
-// Manage universal devices
+// Select (throws if not found)
-dm.addUniversalDevice(device);
+dm.selectDevice({ address: '192.168.1.100' });
-dm.addFeatureToDevice(deviceId, feature);
+
-dm.removeFeatureFromDevice(deviceId, featureType);
+// Discovery
+dm.discoverScanners('192.168.1.0/24');
+dm.discoverPrinters('192.168.1.0/24');
+dm.scanNetwork({ ipRange: '...', probeEscl: true, ... });
+dm.startDiscovery();  // mDNS/SSDP
+dm.stopDiscovery();
 ```
 
-## Protocol Implementations
+## UniversalDevice API
-- `EsclProtocol` - eSCL/AirScan scanner protocol
-- `SaneProtocol` - SANE network scanner protocol
-- `IppProtocol` - IPP printer protocol
-- `SnmpProtocol` - SNMP queries
-- `NutProtocol` - Network UPS Tools protocol
 
-## Type Notes
+```typescript
-- `TScanFormat` includes 'tiff' (added for compatibility)
+// Feature access
-- `IPrinterCapabilities` (from index.ts) has `string[]` for sides/quality
+device.hasFeature('scan');
-- `IPrintCapabilities` (from feature.interfaces.ts) has typed arrays
+device.getFeature<ScanFeature>('scan');       // Returns undefined if not found
+device.selectFeature<ScanFeature>('scan');    // Throws if not found
+device.getFeatureTypes();                      // ['scan', 'print', ...]
+
+// Connection
+await device.connect();      // Connect all features
+await device.disconnect();   // Disconnect all features
+```
+
+## Testing Notes
+
+- Test files use `@git.zone/tstest` with tap-based assertions
+- Import `expect` from `@git.zone/tstest/tapbundle`
+- Tests are in `test/` directory
+- Run with `pnpm test` or `tstest test/test.some.ts --verbose`

readme.md

@@ -468,6 +468,8 @@ type TFeatureType =
 
 ### Custom Device Creation
 
+Use the factory functions for creating devices with specific features:
+
 ```typescript
 import { createScanner, createPrinter, createSpeaker } from '@ecobridge.xyz/devicemanager';
 
@@ -487,8 +489,7 @@ const printer = createPrinter({
   name: 'Office Printer',
   address: '192.168.1.51',
   port: 631,
-  ippPath: '/ipp/print',
+  txtRecords: { rp: '/ipp/print' },
-  txtRecords: {},
 });
 
 // Create a Sonos speaker
@@ -498,7 +499,37 @@ const speaker = createSpeaker({
   address: '192.168.1.52',
   port: 1400,
   protocol: 'sonos',
-  txtRecords: {},
+});
+```
+
+### 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,
+  },
 });
 ```
 
@@ -563,7 +594,7 @@ const maybePrint = device.getFeature<PrintFeature>('print'); // undefined
 
 ## 🙏 Credits
 
-Built with love using:
+Built with ❤️ using:
 - [bonjour-service](https://github.com/onlxltd/bonjour-service) - mDNS discovery
 - [node-ssdp](https://github.com/diversario/node-ssdp) - SSDP/UPnP discovery
 - [net-snmp](https://github.com/markabrahams/node-net-snmp) - SNMP protocol

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@ecobridge.xyz/devicemanager',
-  version: '3.0.0',
+  version: '3.0.2',
   description: 'a device manager for talking to devices on network and over usb'
 }