@ecobridge.xyz/devicemanager 3.0.2

package/.gitea/workflows/default_nottags.yaml

@@ -0,0 +1,66 @@
+name: Default (not tags)
+
+on:
+  push:
+    tags-ignore:
+      - '**'
+
+env:
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@code.foss.global/${{gitea.repository}}.git
+  NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
+  NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
+  NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
+  NPMCI_URL_CLOUDLY: ${{secrets.NPMCI_URL_CLOUDLY}}
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install pnpm and npmci
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+
+      - name: Run npm prepare
+        run: npmci npm prepare
+
+      - name: Audit production dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --prod
+        continue-on-error: true
+
+      - name: Audit development dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --dev
+        continue-on-error: true
+
+  test:
+    if: ${{ always() }}
+    needs: security
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Test stable
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm test
+
+      - name: Test build
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm build

package/.gitea/workflows/default_tags.yaml

@@ -0,0 +1,124 @@
+name: Default (tags)
+
+on:
+  push:
+    tags:
+      - '*'
+
+env:
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@code.foss.global/${{gitea.repository}}.git
+  NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
+  NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
+  NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
+  NPMCI_URL_CLOUDLY: ${{secrets.NPMCI_URL_CLOUDLY}}
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Audit production dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --prod
+        continue-on-error: true
+
+      - name: Audit development dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --dev
+        continue-on-error: true
+
+  test:
+    if: ${{ always() }}
+    needs: security
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Test stable
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm test
+
+      - name: Test build
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm build
+
+  release:
+    needs: test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Release
+        run: |
+          npmci node install stable
+          npmci npm publish
+
+  metadata:
+    needs: test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Code quality
+        run: |
+          npmci command npm install -g typescript
+          npmci npm install
+
+      - name: Trigger
+        run: npmci trigger
+
+      - name: Build docs and upload artifacts
+        run: |
+          npmci node install stable
+          npmci npm install
+          pnpm install -g @git.zone/tsdoc
+          npmci command tsdoc
+        continue-on-error: true

package/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "npm test",
+      "name": "Run npm test",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1,26 @@
+{
+  "json.schemas": [
+    {
+      "fileMatch": ["/npmextra.json"],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "npmci": {
+            "type": "object",
+            "description": "settings for npmci"
+          },
+          "gitzone": {
+            "type": "object",
+            "description": "settings for gitzone",
+            "properties": {
+              "projectType": {
+                "type": "string",
+                "enum": ["website", "element", "service", "npm", "wcc"]
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/changelog.md

@@ -0,0 +1,91 @@
+# 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
+
+- Replace protocol-specific device classes (Scanner, Printer) with UniversalDevice and feature objects (ScanFeature, PrintFeature, PlaybackFeature, VolumeFeature, PowerFeature, SnmpFeature)
+- Add device factory functions: createScanner, createPrinter, createSpeaker, createUpsDevice
+- Add DeviceManager.getDevices selector and updated selectDevice behavior (throws when no match)
+- Expose SnmpProtocol and other protocol implementations
+- Introduce IP helper utilities: isValidIp, cidrToIps, getLocalSubnet
+- Update tests and logging to use feature-based APIs and factories (selectFeature/getFeature, hasFeature, featureCount)
+
+## 2026-01-09 - 2.3.1 - fix(readme)
+update README to comprehensive, TypeScript-first documentation covering installation, quick start, examples, API usage, events, error handling, requirements, credits, and legal/company information
+
+- Rewrote readme.md with ~590 additional lines to provide a full usage guide and examples
+- Added installation instructions for pnpm, npm, and yarn and badges for npm and license
+- Documented OOP usage pattern (Discovery → Selection → Feature → Operation), event handling, and error handling examples
+- Clarified requirements (Node.js 18+, TypeScript 5.0+), credits, license, trademark and company contact information
+- Docs-only change — no code or API modifications
+
+## 2026-01-09 - 2.3.0 - feat(devicemanager)
+add selector-based device APIs, selectFeature helper, convenience discovery methods, and ESCL scan completion fallback
+
+- Introduce IDeviceSelector and add selector support to getDevices(selector) to filter devices by id,address,name,model,manufacturer and feature capabilities.
+- Add selectDevice(selector) which returns exactly one device (throws if none) and logs a warning if multiple matches are returned without a unique identifier.
+- Deprecate getDevice(id) and getDeviceByAddress(address) in favor of selector-based retrieval methods.
+- Add private matchesSelector(...) implementing exact identity checks (id,address), case-insensitive partial attribute matching (name, model, manufacturer), and feature availability checks (hasFeature, hasFeatures, hasAnyFeature).
+- Add selectFeature(type) on devices to provide fail-fast access to a required feature (throws if missing).
+- Add discoverScanners(subnet, options) and discoverPrinters(subnet, options) convenience methods that run targeted network scans and return discovered scanners or printers respectively.
+- Improve ESCL protocol waitForScanComplete to attempt a direct download first (which triggers/blocks on many scanners) and fall back to polling if direct download fails or returns empty data.
+
+## 2026-01-09 - 2.2.0 - feat(smarthome)
+add smart home features and Home Assistant integration (WebSocket protocol, discovery, factories, interfaces)
+
+- Add concrete smart home feature implementations: light, climate, sensor, switch, cover, lock, fan, camera.
+- Introduce Home Assistant WebSocket protocol handler (protocol.homeassistant) and Home Assistant discovery via mDNS (discovery.classes.homeassistant).
+- Add generic smart home interfaces and Home Assistant-specific interfaces (smarthome.interfaces, homeassistant.interfaces) and export them.
+- Add smart home factories to create devices for discovered/declared smart home entities and export factory helpers.
+- Update plugins to include WebSocket (ws) and add ws dependency and @types/ws in package.json.
+
+## 2026-01-09 - 2.1.0 - feat(devicemanager)
+prefer higher-priority discovery source when resolving device names and track per-device name source
+
+- Add TNameSource type and NAME_SOURCE_PRIORITY to rank name sources (generic, manual, airplay, chromecast, mdns, dlna, sonos).
+- Replace chooseBestName with shouldUpdateName that validates 'real' names and uses source priority when deciding to update a device name.
+- Add nameSourceByIp map to track which discovery source provided the current name and persist updates during registration.
+- Register devices with an explicit nameSource (e.g. 'mdns', 'dlna', 'sonos', 'manual') and map speaker protocols to appropriate name sources.
+- Ensure manual additions use 'manual' source and non-real names default to 'generic'.
+- Clear nameSourceByIp entries when devices are removed/disconnected and on shutdown.
+
+## 2026-01-09 - 2.0.0 - BREAKING CHANGE(core)
+rework core device architecture: consolidate protocols into a protocols/ module, introduce UniversalDevice + factories, and remove many legacy device-specific classes (breaking API changes)
+
+- Consolidated protocol implementations into ts/protocols and added protocols/index.ts for unified exports.
+- Added device factory layer at ts/factories/index.ts to create UniversalDevice instances with appropriate features.
+- Introduced protocols/protocol.upssnmp.ts (UPS SNMP handler) and other protocol reorganizations.
+- Removed legacy concrete device classes and related files (Device abstract, Scanner, Printer, SnmpDevice, UpsDevice, DlnaRenderer/Server, Speaker and Sonos/AirPlay/Chromecast implementations).
+- Updated top-level ts/index.ts exports to prefer UniversalDevice, factories and the new protocols module.
+- Updated feature and discovery modules to import protocols from the new protocols index (import path changes).
+- BREAKING: Consumers must update imports and device creation flows to use the new factories/UniversalDevice and protocols exports instead of the removed legacy classes.
+
+## 2026-01-09 - 1.1.0 - feat(devicemanager)
+Introduce a UniversalDevice architecture with composable Feature system; add extensive new device/protocol support and discovery/refactors
+
+- Add UniversalDevice class and Feature abstraction with concrete features: scan, print, playback, volume, power, snmp, dlna-render/serve.
+- Add SSDP discovery and DLNA implementations (renderer + server) and integrate SSDP into DeviceManager.
+- Add speaker subsystem and concrete speaker implementations: Sonos, AirPlay, Chromecast, plus generic Speaker API and Volume/Playback features.
+- Add SNMP feature and SNMP device handling plus UPS support (NUT and UPS SNMP handlers and UpsDevice).
+- Refactor protocol implementations: move/replace scanner/printer protocol code into protocols/ (eSCL, SANE, IPP) and update network scanner to probe additional ports (AirPlay, Sonos, Chromecast) and device types.
+- Update exports (ts/index.ts) to expose new modules, types and helpers; update plugins import handling (node-ssdp default export compatibility).
+- Add developer docs readme.hints.md describing new architecture and feature APIs, and various helper fixes (iprange/os import, typed socket handlers).
+
+## 2026-01-09 - 1.0.1 - initial
+Initial project release.
+
+- Project initialized (initial commit).
+- Duplicate initial commits consolidated into this release.

package/dist_ts/00_commitinfo_data.d.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export declare const commitinfo: {
+    name: string;
+    version: string;
+    description: string;
+};

package/dist_ts/00_commitinfo_data.js

@@ -0,0 +1,9 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+    name: '@ecobridge.xyz/devicemanager',
+    version: '3.0.2',
+    description: 'a device manager for talking to devices on network and over usb'
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSw4QkFBOEI7SUFDcEMsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLGlFQUFpRTtDQUMvRSxDQUFBIn0=

package/dist_ts/device/device.classes.device.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Universal Device class
+ * A device is a network endpoint that can have multiple features (capabilities)
+ */
+import * as plugins from '../plugins.js';
+import type { TFeatureType, IFeatureInfo, IDiscoveredFeature } from '../interfaces/feature.interfaces.js';
+import type { TDeviceStatus, IRetryOptions } from '../interfaces/index.js';
+import { Feature, type TDeviceReference } from '../features/feature.abstract.js';
+/**
+ * Serializable device information
+ */
+export interface IUniversalDeviceInfo {
+    id: string;
+    name: string;
+    address: string;
+    port: number;
+    status: TDeviceStatus;
+    manufacturer?: string;
+    model?: string;
+    serialNumber?: string;
+    firmwareVersion?: string;
+    features: IFeatureInfo[];
+    featureTypes: TFeatureType[];
+}
+/**
+ * Options for creating a device
+ */
+export interface IDeviceCreateOptions {
+    name?: string;
+    manufacturer?: string;
+    model?: string;
+    serialNumber?: string;
+    firmwareVersion?: string;
+    retryOptions?: IRetryOptions;
+}
+/**
+ * Universal Device - represents any network device with composable features
+ *
+ * Instead of having separate Scanner, Printer, Speaker classes, a Device can have
+ * any combination of features (scan, print, playback, volume, etc.)
+ *
+ * @example
+ * ```typescript
+ * // A multifunction printer/scanner
+ * const mfp = new UniversalDevice('192.168.1.100', 80);
+ * mfp.addFeature(new ScanFeature(mfp, 80));
+ * mfp.addFeature(new PrintFeature(mfp, 631));
+ *
+ * // Check capabilities
+ * if (mfp.hasFeature('scan') && mfp.hasFeature('print')) {
+ *   const scanFeature = mfp.getFeature<ScanFeature>('scan');
+ *   await scanFeature.scan({ format: 'pdf' });
+ * }
+ * ```
+ */
+export declare class UniversalDevice extends plugins.events.EventEmitter {
+    /**
+     * Unique device identifier
+     * Format: {address}:{port} or custom ID from discovery
+     */
+    readonly id: string;
+    /**
+     * Human-readable device name
+     */
+    name: string;
+    /**
+     * Device network address (IP or hostname)
+     */
+    readonly address: string;
+    /**
+     * Primary device port
+     */
+    readonly port: number;
+    /**
+     * Device manufacturer
+     */
+    manufacturer?: string;
+    /**
+     * Device model
+     */
+    model?: string;
+    /**
+     * Device serial number
+     */
+    serialNumber?: string;
+    /**
+     * Device firmware version
+     */
+    firmwareVersion?: string;
+    /**
+     * Current device status
+     */
+    protected _status: TDeviceStatus;
+    /**
+     * Map of features by type
+     */
+    protected _features: Map<TFeatureType, Feature>;
+    /**
+     * Retry options for features
+     */
+    protected _retryOptions: IRetryOptions;
+    constructor(address: string, port: number, options?: IDeviceCreateOptions);
+    /**
+     * Get current device status
+     */
+    get status(): TDeviceStatus;
+    /**
+     * Set device status
+     */
+    set status(value: TDeviceStatus);
+    /**
+     * Check if device is online
+     */
+    get isOnline(): boolean;
+    /**
+     * Add a feature to the device
+     */
+    addFeature(feature: Feature): void;
+    /**
+     * Remove a feature from the device
+     */
+    removeFeature(type: TFeatureType): Promise<boolean>;
+    /**
+     * Check if device has a specific feature
+     */
+    hasFeature(type: TFeatureType): boolean;
+    /**
+     * Check if device has all specified features
+     */
+    hasFeatures(types: TFeatureType[]): boolean;
+    /**
+     * Check if device has any of the specified features
+     */
+    hasAnyFeature(types: TFeatureType[]): boolean;
+    /**
+     * Get a feature by type (returns undefined if not available)
+     */
+    getFeature<T extends Feature>(type: TFeatureType): T | undefined;
+    /**
+     * Select a feature by type (throws if not available).
+     * Use this when you expect the device to have this feature and want fail-fast behavior.
+     *
+     * @param type The feature type to select
+     * @returns The feature instance
+     * @throws Error if the device does not have this feature
+     *
+     * @example
+     * ```typescript
+     * const scanFeature = device.selectFeature<ScanFeature>('scan');
+     * await scanFeature.connect();
+     * const result = await scanFeature.scan({ source: 'flatbed' });
+     * ```
+     */
+    selectFeature<T extends Feature>(type: TFeatureType): T;
+    /**
+     * Get all features
+     */
+    getFeatures(): Feature[];
+    /**
+     * Get all feature types
+     */
+    getFeatureTypes(): TFeatureType[];
+    /**
+     * Get feature count
+     */
+    get featureCount(): number;
+    /**
+     * Connect all features
+     */
+    connect(): Promise<void>;
+    /**
+     * Connect a specific feature
+     */
+    connectFeature(type: TFeatureType): Promise<void>;
+    /**
+     * Disconnect all features
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Disconnect a specific feature
+     */
+    disconnectFeature(type: TFeatureType): Promise<void>;
+    /**
+     * Get device reference for features
+     */
+    getDeviceReference(): TDeviceReference;
+    /**
+     * Get serializable device info
+     */
+    getDeviceInfo(): IUniversalDeviceInfo;
+    /**
+     * Get retry options for features
+     */
+    get retryOptions(): IRetryOptions;
+    /**
+     * Create a device from discovered features
+     */
+    static fromDiscovery(id: string, name: string, address: string, port: number, discoveredFeatures: IDiscoveredFeature[], options?: IDeviceCreateOptions): UniversalDevice;
+}
+/**
+ * Check if a device has a specific feature (type guard)
+ */
+export declare function deviceHasFeature<T extends Feature>(device: UniversalDevice, type: TFeatureType): device is UniversalDevice & {
+    getFeature(type: TFeatureType): T;
+};