@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/zwave_js/zwave_js.mapper.ts

@@ -1,321 +1,194 @@
 import * as plugins from '../../plugins.js';
-import type { IIntegrationEntity, IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
-import type { IZwaveJsConfig, IZwaveJsNode, IZwaveJsServerCommand, IZwaveJsSnapshot, IZwaveJsValue, IZwaveJsValueId } from './zwave_js.types.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
+import type { IZwaveJsNode, IZwaveJsServerCommand, IZwaveJsSnapshot, IZwaveJsValue, IZwaveJsValueId, TZwaveJsControlValue } from './zwave_js.types.js';
+import { parseZwaveJsValueId, zwaveJsRecord, zwaveJsValueKey } from './zwave_js.validation.js';
+
+interface IControlTarget { node: IZwaveJsNode; value: IZwaveJsValue }
 
 export class ZwaveJsMapper {
-  public static toSnapshot(configArg: IZwaveJsConfig, connectedArg = false, eventsArg: IZwaveJsSnapshot['events'] = []): IZwaveJsSnapshot {
-    return {
-      version: configArg.version,
-      controller: configArg.controller || configArg.state?.controller,
-      nodes: configArg.nodes || configArg.state?.nodes || [],
-      events: eventsArg,
-      connected: connectedArg,
-      url: configArg.url,
-    };
+  /** Pure mapping helper; runtime setup always obtains its state from the server. */
+  public static toSnapshot(snapshotArg: Partial<IZwaveJsSnapshot>, connectedArg = false,
+    eventsArg: IZwaveJsSnapshot['events'] = []): IZwaveJsSnapshot {
+    return structuredClone({ ...snapshotArg, nodes: snapshotArg.nodes ?? [], events: eventsArg, connected: connectedArg });
   }
 
   public static toDevices(snapshotArg: IZwaveJsSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
     const updatedAt = new Date().toISOString();
-    const devices: plugins.shxInterfaces.data.IDeviceDefinition[] = [];
-    devices.push({
-      id: this.controllerDeviceId(snapshotArg),
-      integrationDomain: 'zwave_js',
-      name: 'Z-Wave controller',
-      protocol: 'zwave',
-      manufacturer: 'Z-Wave JS',
-      model: 'Controller',
-      online: snapshotArg.connected || Boolean(snapshotArg.nodes.length),
+    const devices: plugins.shxInterfaces.data.IDeviceDefinition[] = [{
+      id: this.controllerDeviceId(snapshotArg), integrationDomain: 'zwave_js', name: 'Z-Wave controller',
+      protocol: 'zwave', manufacturer: 'Z-Wave JS', model: 'Controller', online: snapshotArg.connected,
       features: [
         { id: 'connection', capability: 'sensor', name: 'Connection', readable: true, writable: false },
         { id: 'node_count', capability: 'sensor', name: 'Node count', readable: true, writable: false },
       ],
       state: [
-        { featureId: 'connection', value: snapshotArg.connected ? 'connected' : 'configured', updatedAt },
+        { featureId: 'connection', value: snapshotArg.connected ? 'connected' : 'disconnected', updatedAt },
         { featureId: 'node_count', value: snapshotArg.nodes.length, updatedAt },
       ],
-      metadata: {
-        homeId: snapshotArg.controller?.homeId ?? snapshotArg.version?.homeId,
-        serverVersion: snapshotArg.version?.serverVersion,
-        driverVersion: snapshotArg.version?.driverVersion,
-        url: snapshotArg.url,
-      },
-    });
-
+      metadata: { homeId: this.homeId(snapshotArg), serverVersion: snapshotArg.version?.serverVersion, driverVersion: snapshotArg.version?.driverVersion },
+    }];
     for (const node of snapshotArg.nodes) {
-      const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
-        { id: 'status', capability: 'sensor', name: 'Node status', readable: true, writable: false },
-      ];
-      const state: plugins.shxInterfaces.data.IDeviceState[] = [
-        { featureId: 'status', value: node.status || (node.ready ? 'ready' : 'unknown'), updatedAt },
-      ];
-      for (const value of this.nodeValues(node)) {
-        const feature = this.featureForValue(value);
-        features.push(feature);
-        state.push({ featureId: feature.id, value: this.stateValue(value.value), updatedAt });
-      }
+      const values = this.nodeValues(node).filter((valueArg) => valueArg.metadata?.secret !== true);
       devices.push({
-        id: this.nodeDeviceId(node),
-        integrationDomain: 'zwave_js',
-        name: this.nodeName(node),
-        room: node.location,
-        protocol: 'zwave',
-        manufacturer: node.manufacturer,
+        id: this.nodeDeviceId(snapshotArg, node.nodeId), integrationDomain: 'zwave_js', name: this.nodeName(node),
+        room: node.location, protocol: 'zwave', manufacturer: node.manufacturer,
         model: node.productLabel || node.productDescription,
-        online: node.status ? !['dead', 'asleep'].includes(node.status.toLowerCase()) : node.ready !== false,
-        features,
-        state,
-        metadata: {
-          nodeId: node.nodeId,
-          manufacturerId: node.manufacturerId,
-          productId: node.productId,
-          productType: node.productType,
-          firmwareVersion: node.firmwareVersion,
-          isControllerNode: node.isControllerNode,
-        },
+        online: this.nodeAvailable(snapshotArg, node),
+        features: [
+          { id: 'status', capability: 'sensor', name: 'Node status', readable: true, writable: false },
+          ...values.map((valueArg): plugins.shxInterfaces.data.IDeviceFeature => ({
+            id: this.featureId(valueArg), capability: this.platformForValue(valueArg) === 'light' ? 'light' :
+              this.platformForValue(valueArg) === 'switch' ? 'switch' : 'sensor',
+            name: this.valueLabel(valueArg), readable: valueArg.metadata?.readable === true,
+            writable: this.valueWritable(valueArg), unit: valueArg.metadata?.unit,
+          })),
+        ],
+        state: [
+          { featureId: 'status', value: node.status ?? 'unknown', updatedAt },
+          ...values.filter((valueArg) => valueArg.metadata?.readable === true).map((valueArg) => ({
+            featureId: this.featureId(valueArg), value: this.stateValue(valueArg.value), updatedAt,
+          })),
+        ],
+        metadata: { homeId: this.homeId(snapshotArg), nodeId: node.nodeId, manufacturerId: node.manufacturerId,
+          productId: node.productId, productType: node.productType, firmwareVersion: node.firmwareVersion },
       });
     }
     return devices;
   }
 
   public static toEntities(snapshotArg: IZwaveJsSnapshot): IIntegrationEntity[] {
-    const entities: IIntegrationEntity[] = [];
-    for (const node of snapshotArg.nodes) {
-      const deviceId = this.nodeDeviceId(node);
-      for (const value of this.nodeValues(node)) {
-        const platform = this.platformForValue(value);
-        entities.push({
-          id: `${platform}.${this.slug(`${this.nodeName(node)} ${this.valueLabel(value)}`)}`,
-          uniqueId: `zwave_js_${this.slug(`${node.nodeId}_${this.valueIdKey(value)}`)}`,
-          integrationDomain: 'zwave_js',
-          deviceId,
-          platform,
-          name: this.valueLabel(value),
-          state: this.entityState(value, platform),
-          attributes: {
-            nodeId: node.nodeId,
-            valueId: this.valueId(value),
-            commandClass: value.commandClass,
-            commandClassName: value.commandClassName,
-            endpoint: value.endpoint,
-            property: value.property,
-            propertyKey: value.propertyKey,
-            unit: value.metadata?.unit,
-            zwaveType: value.metadata?.type,
-            states: value.metadata?.states,
-          },
-          available: node.ready !== false && node.status !== 'dead',
-        });
-      }
-    }
-    return entities;
+    return snapshotArg.nodes.flatMap((nodeArg) => this.nodeValues(nodeArg)
+      .filter((valueArg) => valueArg.metadata?.secret !== true)
+      .map((valueArg): IIntegrationEntity => {
+        const platform = this.platformForValue(valueArg);
+        const identity = `${this.nodeDeviceId(snapshotArg, nodeArg.nodeId)}.${this.featureId(valueArg)}`;
+        return {
+          id: `${platform}.${identity}`, uniqueId: identity, integrationDomain: 'zwave_js',
+          deviceId: this.nodeDeviceId(snapshotArg, nodeArg.nodeId), platform, name: this.valueLabel(valueArg),
+          state: valueArg.metadata?.readable === true ? this.entityState(valueArg, platform) : 'unknown',
+          attributes: { homeId: this.homeId(snapshotArg), nodeId: nodeArg.nodeId, valueId: this.valueId(valueArg),
+            featureId: this.featureId(valueArg), unit: valueArg.metadata?.unit, writable: this.valueWritable(valueArg) },
+          available: this.nodeAvailable(snapshotArg, nodeArg),
+        };
+      }));
   }
 
   public static commandForService(snapshotArg: IZwaveJsSnapshot, requestArg: IServiceCallRequest): IZwaveJsServerCommand | undefined {
+    if (!['switch', 'light', 'zwave_js'].includes(requestArg.domain) ||
+      !['turn_on', 'turn_off', 'set_value'].includes(requestArg.service)) return undefined;
     const target = this.findTargetValue(snapshotArg, requestArg);
-    if (!target) {
-      return undefined;
-    }
-    let value: unknown;
-    if (requestArg.service === 'turn_on') {
-      value = this.onValue(target.value);
-    } else if (requestArg.service === 'turn_off') {
-      value = this.offValue(target.value);
-    } else if (requestArg.service === 'set_value') {
-      value = requestArg.data?.value;
-    } else if (requestArg.service === 'set_position') {
-      value = requestArg.data?.position;
-    } else if (requestArg.service === 'select_option') {
-      value = requestArg.data?.option;
-    } else if (requestArg.service === 'set_percentage') {
-      value = requestArg.data?.percentage;
-    } else if (requestArg.service === 'open_cover') {
-      value = 99;
-    } else if (requestArg.service === 'close_cover') {
-      value = 0;
-    } else if (requestArg.service === 'press') {
-      value = true;
-    }
-    if (value === undefined) {
-      return undefined;
-    }
-    return {
-      command: 'node.set_value',
-      nodeId: target.node.nodeId,
-      valueId: this.valueId(target.value),
-      value,
-    };
+    if (!target) return undefined;
+    const platform = this.platformForValue(target.value);
+    if (requestArg.domain !== 'zwave_js' && requestArg.domain !== platform) return undefined;
+    const value = requestArg.service === 'turn_on' ? (target.value.commandClass === 37 ? true : 99) :
+      requestArg.service === 'turn_off' ? (target.value.commandClass === 37 ? false : 0) : requestArg.data?.value;
+    return this.createCommand(snapshotArg, target, value);
   }
 
-  public static valueId(valueArg: IZwaveJsValue): IZwaveJsValueId {
-    return {
-      commandClass: valueArg.commandClass || 0,
-      endpoint: valueArg.endpoint,
-      property: valueArg.property ?? valueArg.propertyName ?? 'value',
-      propertyKey: valueArg.propertyKey,
-    };
+  public static commandForFeature(snapshotArg: IZwaveJsSnapshot, requestArg: IDeviceFeatureWriteRequest): IZwaveJsServerCommand {
+    const node = snapshotArg.nodes.find((nodeArg) => this.nodeDeviceId(snapshotArg, nodeArg.nodeId) === requestArg.device.id);
+    const value = node && this.nodeValues(node).find((valueArg) => this.featureId(valueArg) === requestArg.feature.id);
+    if (!node || !value) throw new Error('Z-Wave JS feature target is not in the verified network.');
+    return this.createCommand(snapshotArg, { node, value }, requestArg.value);
   }
 
-  public static nodeValues(nodeArg: IZwaveJsNode): IZwaveJsValue[] {
-    if (Array.isArray(nodeArg.values)) {
-      return nodeArg.values.map((valueArg) => ({ ...valueArg, nodeId: nodeArg.nodeId }));
+  public static validateCommand(snapshotArg: IZwaveJsSnapshot, commandArg: IZwaveJsServerCommand): IZwaveJsServerCommand {
+    if (!zwaveJsRecord(commandArg) || commandArg.command !== 'node.set_value' ||
+      Object.keys(commandArg).some((keyArg) => !['command', 'nodeId', 'valueId', 'value'].includes(keyArg))) {
+      throw new Error('Unsupported Z-Wave JS command.');
     }
-    if (nodeArg.values && typeof nodeArg.values === 'object') {
-      return Object.entries(nodeArg.values).map(([id, value]) => ({ ...value, id, nodeId: nodeArg.nodeId }));
+    const id = parseZwaveJsValueId(commandArg.valueId);
+    if (Object.keys(commandArg.valueId).some((keyArg) => !['commandClass', 'endpoint', 'property', 'propertyKey'].includes(keyArg))) {
+      throw new Error('Invalid Z-Wave JS control identity fields.');
     }
-    return [];
+    const node = snapshotArg.nodes.find((nodeArg) => nodeArg.nodeId === commandArg.nodeId);
+    const value = node && this.nodeValues(node).find((valueArg) => zwaveJsValueKey(valueArg) === zwaveJsValueKey(id));
+    if (!node || !value) throw new Error('Z-Wave JS command target is not in the verified network.');
+    return this.createCommand(snapshotArg, { node, value }, commandArg.value);
   }
 
-  private static findTargetValue(snapshotArg: IZwaveJsSnapshot, requestArg: IServiceCallRequest): { node: IZwaveJsNode; value: IZwaveJsValue } | undefined {
-    const entities = this.toEntities(snapshotArg);
-    if (requestArg.target.entityId) {
-      const entity = entities.find((entityArg) => entityArg.id === requestArg.target.entityId || entityArg.uniqueId === requestArg.target.entityId);
-      if (!entity) {
-        return undefined;
-      }
-      return this.nodeValueByUniqueId(snapshotArg, entity.uniqueId);
-    }
-    if (requestArg.target.deviceId) {
-      const node = snapshotArg.nodes.find((nodeArg) => this.nodeDeviceId(nodeArg) === requestArg.target.deviceId);
-      const value = node ? this.nodeValues(node).find((valueArg) => this.valueWritable(valueArg)) : undefined;
-      return node && value ? { node, value } : undefined;
-    }
-    for (const node of snapshotArg.nodes) {
-      const value = this.nodeValues(node).find((valueArg) => this.valueWritable(valueArg));
-      if (value) {
-        return { node, value };
-      }
-    }
-    return undefined;
+  public static valueId(valueArg: IZwaveJsValue): IZwaveJsValueId {
+    return parseZwaveJsValueId(valueArg);
   }
 
-  private static nodeValueByUniqueId(snapshotArg: IZwaveJsSnapshot, uniqueIdArg: string): { node: IZwaveJsNode; value: IZwaveJsValue } | undefined {
-    for (const node of snapshotArg.nodes) {
-      for (const value of this.nodeValues(node)) {
-        if (`zwave_js_${this.slug(`${node.nodeId}_${this.valueIdKey(value)}`)}` === uniqueIdArg) {
-          return { node, value };
-        }
-      }
-    }
-    return undefined;
+  public static featureId(valueArg: IZwaveJsValue): string {
+    return `value.${encodeURIComponent(zwaveJsValueKey(valueArg))}`;
   }
 
-  private static featureForValue(valueArg: IZwaveJsValue): plugins.shxInterfaces.data.IDeviceFeature {
-    const platform = this.platformForValue(valueArg);
-    return {
-      id: this.slug(this.valueIdKey(valueArg)),
-      capability: this.capabilityForPlatform(platform),
-      name: this.valueLabel(valueArg),
-      readable: valueArg.metadata?.readable !== false,
-      writable: this.valueWritable(valueArg),
-      unit: valueArg.metadata?.unit,
-    };
+  public static nodeValues(nodeArg: IZwaveJsNode): IZwaveJsValue[] {
+    return structuredClone(Array.isArray(nodeArg.values) ? nodeArg.values : Object.values(nodeArg.values ?? {}));
   }
 
-  private static platformForValue(valueArg: IZwaveJsValue): TEntityPlatform {
-    const label = this.valueLabel(valueArg).toLowerCase();
-    const cc = (valueArg.commandClassName || '').toLowerCase();
-    const type = valueArg.metadata?.type;
-    const writable = this.valueWritable(valueArg);
-    if (cc.includes('switch binary') || (type === 'boolean' && writable)) {
-      return 'switch';
-    }
-    if (cc.includes('switch multilevel') && writable) {
-      return 'light';
-    }
-    if (cc.includes('window covering')) {
-      return 'cover';
-    }
-    if (cc.includes('thermostat')) {
-      return 'climate';
-    }
-    if (valueArg.metadata?.states && writable) {
-      return 'select';
-    }
-    if (type === 'number' && writable) {
-      return 'number';
-    }
-    if (type === 'boolean') {
-      return 'binary_sensor';
-    }
-    if (label.includes('firmware')) {
-      return 'update';
-    }
-    return 'sensor';
+  public static nodeDeviceId(snapshotArg: IZwaveJsSnapshot, nodeIdArg: number): string {
+    return `zwave_js.${this.homeId(snapshotArg).toString(16)}.node.${nodeIdArg}`;
   }
 
-  private static capabilityForPlatform(platformArg: TEntityPlatform): plugins.shxInterfaces.data.TDeviceCapability {
-    if (platformArg === 'light') {
-      return 'light';
-    }
-    if (platformArg === 'switch' || platformArg === 'button' || platformArg === 'number' || platformArg === 'select' || platformArg === 'text') {
-      return 'switch';
+  private static createCommand(snapshotArg: IZwaveJsSnapshot, targetArg: IControlTarget, valueArg: unknown): IZwaveJsServerCommand {
+    if (!this.nodeAvailable(snapshotArg, targetArg.node) || !this.valueWritable(targetArg.value)) {
+      throw new Error('Z-Wave JS target is unavailable or is not a supported writable value.');
     }
-    if (platformArg === 'cover') {
-      return 'cover';
+    const metadata = targetArg.value.metadata!;
+    const valid = targetArg.value.commandClass === 37 ? typeof valueArg === 'boolean' :
+      typeof valueArg === 'number' && Number.isFinite(valueArg) && Number.isInteger(valueArg) && valueArg >= 0 && valueArg <= 99;
+    if (!valid || typeof valueArg === 'number' &&
+      (metadata.min !== undefined && valueArg < metadata.min || metadata.max !== undefined && valueArg > metadata.max)) {
+      throw new Error('Z-Wave JS control value violates the advertised type or range.');
     }
-    if (platformArg === 'climate') {
-      return 'climate';
-    }
-    if (platformArg === 'fan') {
-      return 'fan';
-    }
-    return 'sensor';
+    return { command: 'node.set_value', nodeId: targetArg.node.nodeId, valueId: this.valueId(targetArg.value), value: valueArg as TZwaveJsControlValue };
   }
 
-  private static entityState(valueArg: IZwaveJsValue, platformArg: TEntityPlatform): unknown {
-    if (platformArg === 'switch' || platformArg === 'light') {
-      return valueArg.value ? 'on' : 'off';
+  private static findTargetValue(snapshotArg: IZwaveJsSnapshot, requestArg: IServiceCallRequest): IControlTarget | undefined {
+    if (!zwaveJsRecord(requestArg.target) || (!requestArg.target.entityId && !requestArg.target.deviceId)) return undefined;
+    const matches: IControlTarget[] = [];
+    for (const node of snapshotArg.nodes) {
+      if (requestArg.target.deviceId && this.nodeDeviceId(snapshotArg, node.nodeId) !== requestArg.target.deviceId) continue;
+      for (const value of this.nodeValues(node)) {
+        if (!this.valueWritable(value)) continue;
+        const identity = `${this.nodeDeviceId(snapshotArg, node.nodeId)}.${this.featureId(value)}`;
+        if (requestArg.target.entityId && requestArg.target.entityId !== identity &&
+          requestArg.target.entityId !== `${this.platformForValue(value)}.${identity}`) continue;
+        if (requestArg.data?.featureId !== undefined && requestArg.data.featureId !== this.featureId(value)) continue;
+        matches.push({ node, value });
+      }
     }
-    return valueArg.value ?? 'unknown';
+    return matches.length === 1 ? matches[0] : undefined;
   }
 
   private static valueWritable(valueArg: IZwaveJsValue): boolean {
-    return valueArg.metadata?.writeable === true || valueArg.metadata?.writeable === undefined && valueArg.commandClassName?.toLowerCase().includes('switch') === true;
+    return valueArg.metadata?.writeable === true && valueArg.metadata.secret !== true &&
+      valueArg.property === 'targetValue' && (valueArg.commandClass === 37 && valueArg.metadata.type === 'boolean' ||
+        valueArg.commandClass === 38 && valueArg.metadata.type === 'number');
   }
 
-  private static valueLabel(valueArg: IZwaveJsValue): string {
-    return valueArg.metadata?.label || valueArg.propertyName || String(valueArg.property ?? valueArg.id ?? 'Z-Wave value');
-  }
-
-  private static valueIdKey(valueArg: IZwaveJsValue): string {
-    return [valueArg.commandClass, valueArg.endpoint || 0, valueArg.property ?? valueArg.propertyName ?? 'value', valueArg.propertyKey ?? ''].join('_');
-  }
-
-  private static onValue(currentArg: unknown): unknown {
-    return typeof currentArg === 'number' ? 99 : true;
+  private static platformForValue(valueArg: IZwaveJsValue): TEntityPlatform {
+    if (valueArg.commandClass === 37 && valueArg.metadata?.type === 'boolean') return 'switch';
+    if (valueArg.commandClass === 38 && valueArg.metadata?.type === 'number') return 'light';
+    return valueArg.metadata?.type === 'boolean' ? 'binary_sensor' : 'sensor';
   }
 
-  private static offValue(currentArg: unknown): unknown {
-    return typeof currentArg === 'number' ? 0 : false;
+  private static entityState(valueArg: IZwaveJsValue, platformArg: TEntityPlatform): unknown {
+    if ((platformArg === 'switch' || platformArg === 'light') &&
+      (typeof valueArg.value === 'boolean' || typeof valueArg.value === 'number')) return valueArg.value ? 'on' : 'off';
+    return valueArg.value ?? 'unknown';
   }
 
   private static stateValue(valueArg: unknown): plugins.shxInterfaces.data.TDeviceStateValue {
-    if (Array.isArray(valueArg)) {
-      return JSON.stringify(valueArg);
-    }
-    if (typeof valueArg === 'string' || typeof valueArg === 'number' || typeof valueArg === 'boolean' || valueArg === null || this.isRecord(valueArg)) {
-      return valueArg;
-    }
-    return valueArg === undefined ? null : String(valueArg);
-  }
-
-  private static nodeDeviceId(nodeArg: IZwaveJsNode): string {
-    return `zwave_js.node.${nodeArg.nodeId}`;
+    if (Array.isArray(valueArg)) return JSON.stringify(valueArg);
+    if (typeof valueArg === 'string' || typeof valueArg === 'number' || typeof valueArg === 'boolean' || valueArg === null || zwaveJsRecord(valueArg)) return valueArg;
+    return null;
   }
 
-  private static controllerDeviceId(snapshotArg: IZwaveJsSnapshot): string {
-    return `zwave_js.controller.${snapshotArg.controller?.homeId ?? snapshotArg.version?.homeId ?? 'network'}`;
+  private static nodeAvailable(snapshotArg: IZwaveJsSnapshot, nodeArg: IZwaveJsNode): boolean {
+    return snapshotArg.connected && nodeArg.ready === true && ['alive', 'awake', 'asleep'].includes(nodeArg.status ?? '');
   }
 
-  private static nodeName(nodeArg: IZwaveJsNode): string {
-    return nodeArg.name || nodeArg.productLabel || nodeArg.productDescription || `Z-Wave node ${nodeArg.nodeId}`;
+  private static homeId(snapshotArg: IZwaveJsSnapshot): number {
+    const homeId = snapshotArg.controller?.homeId ?? snapshotArg.version?.homeId;
+    if (typeof homeId !== 'number' || !Number.isSafeInteger(homeId) || homeId < 1) throw new Error('Z-Wave JS snapshot has no verified network identity.');
+    return homeId;
   }
 
-  private static isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
-  }
-
-  private static slug(valueArg: string): string {
-    return valueArg.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'zwave_js';
-  }
+  private static controllerDeviceId(snapshotArg: IZwaveJsSnapshot): string { return `zwave_js.${this.homeId(snapshotArg).toString(16)}.controller`; }
+  private static nodeName(nodeArg: IZwaveJsNode): string { return nodeArg.name || nodeArg.productLabel || `Z-Wave node ${nodeArg.nodeId}`; }
+  private static valueLabel(valueArg: IZwaveJsValue): string { return valueArg.metadata?.label || valueArg.propertyName || String(valueArg.property); }
 }

package/ts/integrations/zwave_js/zwave_js.types.ts

@@ -1,31 +1,32 @@
 export interface IZwaveJsConfig {
-  url?: string;
-  schemaVersion?: number;
-  version?: IZwaveJsVersion;
-  state?: IZwaveJsState;
-  nodes?: IZwaveJsNode[];
-  controller?: IZwaveJsController;
+  url: string;
+  expectedHomeId: number;
+  /** Authorization enforced by the operator's TLS reverse proxy, not by Z-Wave JS. */
+  authorization?: string;
+  /** Additional TLS trust anchor. Certificate and hostname verification stay enabled. */
+  ca?: string;
+  requestTimeoutMs?: number;
 }
 
 export interface IZwaveJsVersion {
-  type?: 'version';
-  driverVersion?: string;
-  serverVersion?: string;
-  homeId?: number;
-  minSchemaVersion?: number;
-  maxSchemaVersion?: number;
+  type: 'version';
+  driverVersion: string;
+  serverVersion: string;
+  homeId: number;
+  minSchemaVersion: number;
+  maxSchemaVersion: number;
 }
 
 export interface IZwaveJsState {
   driver?: Record<string, unknown>;
-  controller?: IZwaveJsController;
-  nodes?: IZwaveJsNode[];
+  controller: IZwaveJsController;
+  nodes: IZwaveJsNode[];
 }
 
 export interface IZwaveJsController {
   homeId?: number;
   ownNodeId?: number;
-  status?: string;
+  status?: string | number;
   isUsingHomeIdFromOtherNetwork?: boolean;
   statistics?: Record<string, unknown>;
   [key: string]: unknown;
@@ -65,6 +66,8 @@ export interface IZwaveJsValueMetadata {
   writeable?: boolean;
   unit?: string;
   states?: Record<string, string>;
+  secret?: boolean;
+  stateful?: boolean;
   min?: number;
   max?: number;
   [key: string]: unknown;
@@ -94,14 +97,24 @@ export interface IZwaveJsSnapshot {
   url?: string;
 }
 
+export type TZwaveJsControlValue = boolean | number;
+
 export interface IZwaveJsServerCommand {
-  command: string;
-  [key: string]: unknown;
+  command: 'node.set_value';
+  nodeId: number;
+  valueId: IZwaveJsValueId;
+  value: TZwaveJsControlValue;
+}
+
+export interface IZwaveJsWriteResult {
+  /** Only supervised status 255 proves completion. Status 1/254 remain indeterminate. */
+  outcome: 'confirmed' | 'working' | 'unsupervised' | 'rejected';
+  status: number;
 }
 
 export interface IZwaveJsServerEvent {
-  source?: string;
-  event?: string;
+  source: string;
+  event: string;
   nodeId?: number;
   valueId?: IZwaveJsValueId;
   value?: unknown;