@smarthome.exchange/integrations 0.1.0 → 1.0.0

package/ts/integrations/zwave_js/zwave_js.classes.integration.ts

@@ -1,11 +1,11 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { ZwaveJsClient } from './zwave_js.classes.client.js';
 import { ZwaveJsConfigFlow } from './zwave_js.classes.configflow.js';
 import { createZwaveJsDiscoveryDescriptor } from './zwave_js.discovery.js';
 import { ZwaveJsMapper } from './zwave_js.mapper.js';
-import type { IZwaveJsConfig, IZwaveJsServerCommand } from './zwave_js.types.js';
+import type { IZwaveJsConfig, IZwaveJsServerCommand, IZwaveJsWriteResult } from './zwave_js.types.js';
 
 export class ZwaveJsIntegration extends BaseIntegration<IZwaveJsConfig> {
   public readonly domain = 'zwave_js';
@@ -14,113 +14,97 @@ export class ZwaveJsIntegration extends BaseIntegration<IZwaveJsConfig> {
   public readonly discoveryDescriptor = createZwaveJsDiscoveryDescriptor();
   public readonly configFlow = new ZwaveJsConfigFlow();
   public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/zwave_js',
-    upstreamDomain: 'zwave_js',
-    integrationType: 'hub',
-    iotClass: 'local_push',
-    qualityScale: 'unknown',
+    source: 'zwave-js/zwave-js-server', upstreamPath: 'src/lib', upstreamDomain: 'zwave_js',
+    integrationType: 'hub', iotClass: 'local_push', qualityScale: 'unknown',
   };
+  #clients = new Set<ZwaveJsClient>();
+  #destroyed = false;
 
   public async setup(configArg: IZwaveJsConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new ZwaveJsRuntime(new ZwaveJsClient(configArg));
+    if (this.#destroyed) throw new Error('Z-Wave JS integration is destroyed.');
+    const client = new ZwaveJsClient(configArg, contextArg.abortSignal);
+    this.#clients.add(client);
+    try {
+      await client.start();
+      if (this.#destroyed) throw new Error('Z-Wave JS integration is destroyed.');
+      return new ZwaveJsRuntime(client, () => { this.#clients.delete(client); });
+    } catch (errorArg) {
+      await client.destroy();
+      this.#clients.delete(client);
+      throw errorArg;
+    }
   }
 
-  public async destroy(): Promise<void> {}
+  public async destroy(): Promise<void> {
+    this.#destroyed = true;
+    await Promise.all([...this.#clients].map((clientArg) => clientArg.destroy()));
+    this.#clients.clear();
+  }
 }
 
 export class HomeAssistantZwaveJsIntegration extends ZwaveJsIntegration {}
 
 class ZwaveJsRuntime implements IIntegrationRuntime {
-  public domain = 'zwave_js';
+  public readonly domain = 'zwave_js';
+  #subscriptions = new Set<() => void>();
+  #destroyPromise?: Promise<void>;
 
-  constructor(private readonly client: ZwaveJsClient) {}
+  constructor(private readonly client: ZwaveJsClient, private readonly released: () => void) {}
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return ZwaveJsMapper.toDevices(await this.client.getSnapshot());
-  }
+  public isHealthy(): boolean { return this.client.isHealthy(); }
 
-  public async entities(): Promise<IIntegrationEntity[]> {
-    return ZwaveJsMapper.toEntities(await this.client.getSnapshot());
+  public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return ZwaveJsMapper.toDevices(await this.client.getSnapshot(abortSignalArg));
   }
 
-  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void): Promise<() => Promise<void>> {
+  public async entities(): Promise<IIntegrationEntity[]> { return ZwaveJsMapper.toEntities(await this.client.getSnapshot()); }
+
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    if (abortSignalArg?.aborted) throw new Error('Z-Wave JS subscription was aborted.');
+    const snapshot = await this.client.getSnapshot(abortSignalArg);
     const unsubscribe = this.client.onEvent((eventArg) => {
       handlerArg({
-        type: eventArg.event === 'value updated' ? 'state_changed' : 'device_added',
-        integrationDomain: 'zwave_js',
-        deviceId: typeof eventArg.nodeId === 'number' ? `zwave_js.node.${eventArg.nodeId}` : undefined,
-        data: eventArg,
-        timestamp: Date.now(),
+        type: eventArg.source === 'connection' || ['alive', 'dead', 'sleep', 'wake up'].includes(eventArg.event) ?
+          'availability_changed' : 'state_changed',
+        integrationDomain: this.domain,
+        deviceId: eventArg.nodeId !== undefined ? ZwaveJsMapper.nodeDeviceId(snapshot, eventArg.nodeId) : undefined,
+        data: eventArg, timestamp: Date.now(),
       });
     });
-    await this.client.getSnapshot();
-    return async () => unsubscribe();
+    const release = () => {
+      unsubscribe();
+      abortSignalArg?.removeEventListener('abort', release);
+      this.#subscriptions.delete(release);
+    };
+    this.#subscriptions.add(release);
+    abortSignalArg?.addEventListener('abort', release, { once: true });
+    if (abortSignalArg?.aborted) release();
+    return async () => { release(); };
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.domain === 'zwave_js') {
-      const command = this.commandFromService(requestArg);
-      if (!command) {
-        return { success: false, error: `Unsupported Z-Wave JS service: ${requestArg.service}` };
-      }
-      const data = await this.client.sendCommand(command);
-      return { success: true, data };
-    }
-
     const command = ZwaveJsMapper.commandForService(await this.client.getSnapshot(), requestArg);
-    if (!command) {
-      return { success: false, error: `Z-Wave JS entity service ${requestArg.domain}.${requestArg.service} has no writable value mapping.` };
-    }
-    const data = await this.client.sendCommand(command);
-    return { success: true, data };
+    if (!command) return { success: false, error: 'Unsupported, missing or ambiguous Z-Wave JS control target.' };
+    return this.execute(command);
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    const command = ZwaveJsMapper.commandForFeature(await this.client.getSnapshot(abortSignalArg), requestArg);
+    return this.execute(command, abortSignalArg);
   }
 
-  private commandFromService(requestArg: IServiceCallRequest): IZwaveJsServerCommand | undefined {
-    if (requestArg.service === 'ping') {
-      const nodeId = this.numberValue(requestArg.data?.node_id ?? requestArg.data?.nodeId);
-      return nodeId ? { command: 'node.ping', nodeId } : undefined;
-    }
-    if (requestArg.service === 'refresh_value') {
-      const nodeId = this.numberValue(requestArg.data?.node_id ?? requestArg.data?.nodeId);
-      const valueId = requestArg.data?.value_id ?? requestArg.data?.valueId;
-      return nodeId && this.isRecord(valueId) ? { command: 'node.poll_value', nodeId, valueId } : undefined;
-    }
-    if (requestArg.service === 'set_value') {
-      const nodeId = this.numberValue(requestArg.data?.node_id ?? requestArg.data?.nodeId);
-      const valueId = requestArg.data?.value_id ?? requestArg.data?.valueId;
-      return nodeId && this.isRecord(valueId) ? { command: 'node.set_value', nodeId, valueId, value: requestArg.data?.value } : undefined;
-    }
-    if (requestArg.service === 'set_config_parameter') {
-      const nodeId = this.numberValue(requestArg.data?.node_id ?? requestArg.data?.nodeId);
-      const parameter = this.numberValue(requestArg.data?.parameter);
-      return nodeId && parameter ? { command: 'node.set_raw_config_parameter_value', nodeId, parameter, bitMask: requestArg.data?.bitmask, value: requestArg.data?.value, valueSize: requestArg.data?.value_size, valueFormat: requestArg.data?.value_format } : undefined;
-    }
-    if (requestArg.service === 'begin_inclusion') {
-      return { command: 'controller.begin_inclusion', strategy: requestArg.data?.strategy || 0 };
+  public destroy(): Promise<void> {
+    if (!this.#destroyPromise) {
+      for (const release of this.#subscriptions) release();
+      this.#destroyPromise = this.client.destroy().finally(() => this.released());
     }
-    if (requestArg.service === 'stop_inclusion') {
-      return { command: 'controller.stop_inclusion' };
-    }
-    if (requestArg.service === 'invoke_cc_api') {
-      const nodeId = this.numberValue(requestArg.data?.node_id ?? requestArg.data?.nodeId);
-      const commandClass = this.numberValue(requestArg.data?.command_class ?? requestArg.data?.commandClass);
-      const methodName = requestArg.data?.method_name ?? requestArg.data?.methodName;
-      return nodeId && commandClass && typeof methodName === 'string' ? { command: 'endpoint.invoke_cc_api', nodeId, endpoint: requestArg.data?.endpoint, commandClass, methodName, args: Array.isArray(requestArg.data?.parameters) ? requestArg.data.parameters : [] } : undefined;
-    }
-    return undefined;
-  }
-
-  private numberValue(valueArg: unknown): number | undefined {
-    return typeof valueArg === 'number' && Number.isFinite(valueArg) ? valueArg : undefined;
+    return this.#destroyPromise;
   }
 
-  private isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+  private async execute(commandArg: IZwaveJsServerCommand, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    const data: IZwaveJsWriteResult = await this.client.sendCommand(commandArg, abortSignalArg);
+    return { success: data.outcome === 'confirmed', data,
+      error: data.outcome === 'confirmed' ? undefined : data.outcome === 'rejected' ?
+        'Z-Wave device rejected the control.' : 'Z-Wave control execution is indeterminate; do not retry automatically.' };
   }
 }

package/ts/integrations/zwave_js/zwave_js.discovery.ts

@@ -1,6 +1,7 @@
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
 import type { IZwaveJsManualEntry, IZwaveJsMdnsRecord, IZwaveJsUsbRecord } from './zwave_js.types.js';
+import { validateZwaveJsConfig, zwaveJsRecord } from './zwave_js.validation.js';
 
 const knownUsbIds = new Set(['0658:0200', '10c4:8a2a', '303a:4001', '10c4:ea60']);
 
@@ -11,7 +12,8 @@ export class ZwaveJsMdnsMatcher implements IDiscoveryMatcher<IZwaveJsMdnsRecord>
 
   public async matches(recordArg: IZwaveJsMdnsRecord): Promise<IDiscoveryMatch> {
     const type = (recordArg.type || '').toLowerCase().replace(/\.$/, '');
-    const matched = type === '_zwave-js-server._tcp.local' || Boolean(recordArg.name?.toLowerCase().includes('zwave-js'));
+    const url = recordArg.host ? endpointUrl(recordArg.host, recordArg.port) : undefined;
+    const matched = type === '_zwave-js-server._tcp.local' && Boolean(url);
     if (!matched) {
       return { matched: false, confidence: 'low', reason: 'mDNS record is not a Z-Wave JS Server advertisement.' };
     }
@@ -29,7 +31,7 @@ export class ZwaveJsMdnsMatcher implements IDiscoveryMatcher<IZwaveJsMdnsRecord>
         name: 'Z-Wave JS Server',
         manufacturer: 'Z-Wave JS',
         model: 'WebSocket Server',
-        metadata: { mdnsName: recordArg.name, mdnsType: recordArg.type, txt: recordArg.txt, url: recordArg.host ? `ws://${recordArg.host}:${recordArg.port || 3000}` : undefined },
+        metadata: { mdnsName: recordArg.name, mdnsType: recordArg.type, url },
       },
     };
   }
@@ -73,8 +75,8 @@ export class ZwaveJsManualMatcher implements IDiscoveryMatcher<IZwaveJsManualEnt
 
   public async matches(inputArg: IZwaveJsManualEntry): Promise<IDiscoveryMatch> {
     const model = inputArg.model?.toLowerCase() || '';
-    const url = inputArg.url || (inputArg.host ? `ws://${inputArg.host}:${inputArg.port || 3000}` : undefined);
-    const matched = Boolean(url || inputArg.usbPath || inputArg.metadata?.zwaveJs || model.includes('z-wave') || model.includes('zwave'));
+    const url = inputArg.url ? safeUrl(inputArg.url) : inputArg.host ? endpointUrl(inputArg.host, inputArg.port) : undefined;
+    const matched = Boolean(url || !inputArg.url && (inputArg.usbPath || inputArg.metadata?.zwaveJs || model.includes('z-wave') || model.includes('zwave')));
     if (!matched) {
       return { matched: false, confidence: 'low', reason: 'Manual entry does not contain Z-Wave JS setup hints.' };
     }
@@ -92,7 +94,7 @@ export class ZwaveJsManualMatcher implements IDiscoveryMatcher<IZwaveJsManualEnt
         name: inputArg.name || 'Z-Wave JS',
         manufacturer: 'Z-Wave JS',
         model: inputArg.model || 'WebSocket Server',
-        metadata: { ...inputArg.metadata, url, usbPath: inputArg.usbPath },
+        metadata: { url, usbPath: inputArg.usbPath },
       },
     };
   }
@@ -103,16 +105,22 @@ export class ZwaveJsCandidateValidator implements IDiscoveryValidator {
   public description = 'Validate Z-Wave JS candidate metadata.';
 
   public async validate(candidateArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
-    const model = candidateArg.model?.toLowerCase() || '';
-    const manufacturer = candidateArg.manufacturer?.toLowerCase() || '';
-    const matched = candidateArg.integrationDomain === 'zwave_js' || model.includes('z-wave') || model.includes('zwave') || manufacturer.includes('z-wave') || Boolean(candidateArg.metadata?.zwaveJs);
-    return {
-      matched,
-      confidence: matched && (candidateArg.host || candidateArg.metadata?.url || candidateArg.source === 'usb') ? 'high' : matched ? 'medium' : 'low',
-      reason: matched ? 'Candidate has Z-Wave JS metadata.' : 'Candidate is not Z-Wave JS.',
-      candidate: matched ? candidateArg : undefined,
-      normalizedDeviceId: candidateArg.id,
-    };
+    try {
+      const candidate = sanitizedCandidate(candidateArg);
+      const model = candidate.model?.toLowerCase() ?? '';
+      const manufacturer = candidate.manufacturer?.toLowerCase() ?? '';
+      const matched = candidate.integrationDomain === 'zwave_js' || model.includes('z-wave') ||
+        model.includes('zwave') || manufacturer.includes('z-wave') || candidate.metadata?.zwaveJs === true;
+      return {
+        matched,
+        confidence: matched && (candidate.host || candidate.metadata?.url || candidate.source === 'usb') ? 'high' : matched ? 'medium' : 'low',
+        reason: matched ? 'Candidate has Z-Wave JS metadata.' : 'Candidate is not Z-Wave JS.',
+        candidate: matched ? { ...candidate, integrationDomain: 'zwave_js' } : undefined,
+        normalizedDeviceId: matched ? candidate.id : undefined,
+      };
+    } catch {
+      return { matched: false, confidence: 'low', reason: 'Invalid Z-Wave JS candidate metadata.' };
+    }
   }
 }
 
@@ -123,3 +131,80 @@ export const createZwaveJsDiscoveryDescriptor = (): DiscoveryDescriptor => {
     .addMatcher(new ZwaveJsManualMatcher())
     .addValidator(new ZwaveJsCandidateValidator());
 };
+
+const safeUrl = (urlArg: string): string | undefined => {
+  try { return validateZwaveJsConfig({ url: urlArg, expectedHomeId: 1 }).url.replace(/\/$/, ''); }
+  catch { return undefined; }
+};
+
+const endpointUrl = (hostArg: string, portArg = 3000): string | undefined => {
+  if (!Number.isInteger(portArg) || portArg < 1 || portArg > 65535 || /[\s/@?#]/.test(hostArg)) return undefined;
+  const host = hostArg.includes(':') && !hostArg.startsWith('[') ? `[${hostArg}]` : hostArg;
+  return safeUrl(`ws://${host}:${portArg}`);
+};
+
+const sanitizedCandidate = (inputArg: IDiscoveryCandidate): IDiscoveryCandidate => {
+  if (!zwaveJsRecord(inputArg)) throw new Error('Invalid discovery candidate.');
+  const source = ownData(inputArg, 'source');
+  if (source !== 'manual' && source !== 'mdns' && source !== 'usb') throw new Error('Unsupported Z-Wave JS discovery source.');
+  const candidate: IDiscoveryCandidate = { source };
+  for (const key of ['integrationDomain', 'id', 'host', 'name', 'manufacturer', 'model', 'serialNumber', 'macAddress'] as const) {
+    const value = ownString(inputArg, key);
+    if (value !== undefined) candidate[key] = value;
+  }
+  const port = ownData(inputArg, 'port');
+  if (port !== undefined) {
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Invalid discovery port.');
+    candidate.port = port;
+  }
+  if (candidate.host && !endpointUrl(candidate.host, candidate.port)) throw new Error('Invalid discovery host.');
+  const metadata = ownData(inputArg, 'metadata');
+  if (metadata === undefined) return candidate;
+  if (!zwaveJsRecord(metadata)) throw new Error('Invalid discovery metadata.');
+  const normalized: Record<string, unknown> = {};
+  const url = ownString(metadata, 'url', 2048);
+  if (url !== undefined) {
+    const endpoint = safeUrl(url);
+    if (!endpoint) throw new Error('Invalid discovery endpoint.');
+    normalized.url = endpoint;
+  }
+  const zwaveJs = ownData(metadata, 'zwaveJs');
+  if (zwaveJs !== undefined && typeof zwaveJs !== 'boolean') throw new Error('Invalid discovery hint.');
+  if (zwaveJs === true) normalized.zwaveJs = true;
+  if (source === 'mdns') {
+    const type = ownString(metadata, 'mdnsType');
+    if (type !== undefined) {
+      if (type.toLowerCase().replace(/\.$/, '') !== '_zwave-js-server._tcp.local') throw new Error('Invalid discovery service.');
+      normalized.mdnsType = type;
+    }
+    const name = ownString(metadata, 'mdnsName');
+    if (name !== undefined) normalized.mdnsName = name;
+  }
+  if (source === 'usb' || source === 'manual') {
+    for (const key of source === 'usb' ? ['vid', 'pid', 'path'] : ['usbPath']) {
+      const value = ownString(metadata, key);
+      if (value === undefined) continue;
+      if ((key === 'vid' || key === 'pid') && !/^[0-9a-f]{4}$/i.test(value)) throw new Error('Invalid USB discovery identity.');
+      normalized[key] = value;
+    }
+  }
+  if (Object.keys(normalized).length) candidate.metadata = normalized;
+  return candidate;
+};
+
+/** Read only explicit data fields; discovery input must not execute accessors. */
+const ownData = (inputArg: Record<string, unknown>, keyArg: string): unknown => {
+  const descriptor = Object.getOwnPropertyDescriptor(inputArg, keyArg);
+  if (!descriptor) return undefined;
+  if (!Object.hasOwn(descriptor, 'value')) throw new Error('Discovery accessors are unsupported.');
+  return descriptor.value;
+};
+
+const ownString = (inputArg: Record<string, unknown>, keyArg: string, maxLengthArg = 1024): string | undefined => {
+  const value = ownData(inputArg, keyArg);
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || !value.trim() || value.length > maxLengthArg || /[\x00-\x1f\x7f]/.test(value)) {
+    throw new Error('Invalid discovery text field.');
+  }
+  return value;
+};