@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/zigbee2mqtt/zigbee2mqtt.classes.runtime.ts

@@ -0,0 +1,414 @@
+import type * as plugins from '../../plugins.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { MqttClient } from '../mqtt/mqtt.classes.client.js';
+import type { IMqttMessage } from '../mqtt/mqtt.types.js';
+import { Zigbee2MqttMapper } from './zigbee2mqtt.mapper.js';
+import type { IZigbee2MqttConfig, IZigbee2MqttDevice, IZigbee2MqttReportedState, IZigbee2MqttSnapshot } from './zigbee2mqtt.types.js';
+import { zigbee2MqttConfig, zigbee2MqttRecord } from './zigbee2mqtt.validation.js';
+
+interface IZigbee2MqttListener {
+  handler: (eventArg: IIntegrationEvent) => void;
+  cleanup: () => Promise<void>;
+}
+
+export class Zigbee2MqttRuntime implements IIntegrationRuntime {
+  public readonly domain = 'zigbee2mqtt';
+  private readonly config: IZigbee2MqttConfig;
+  private readonly client: MqttClient;
+  private readonly removeMessageHandler: () => void;
+  private readonly removeConnectionHandler: () => void;
+  private readonly handlers = new Set<IZigbee2MqttListener>();
+  private readonly subscriptionCleanups = new Set<() => Promise<void>>();
+  private readonly readyWaiters = new Set<{ resolve: () => void; reject: (errorArg: Error) => void }>();
+  private readonly pendingMessages = new Map<string, IMqttMessage>();
+  private readonly pendingWrites = new Set<Promise<void>>();
+  private devicesByIeee = new Map<string, IZigbee2MqttDevice>();
+  private devicesByName = new Map<string, IZigbee2MqttDevice>();
+  private readonly availability = new Map<string, boolean>();
+  private readonly state = new Map<string, Map<string, IZigbee2MqttReportedState>>();
+  private bridgeOnline = false;
+  private connected = false;
+  private started = false;
+  private bridgeReceived = false;
+  private inventoryReceived = false;
+  private inventoryCurrent = false;
+  private inventoryError?: Error;
+  private destroyed = false;
+  private destroyPromise?: Promise<void>;
+  private activeWrites = 0;
+  private removeSetupAbort?: () => void;
+
+  constructor(configArg: IZigbee2MqttConfig) {
+    this.config = zigbee2MqttConfig(configArg);
+    this.client = new MqttClient({
+      ...this.config, discovery: false, birthMessage: false, willMessage: false, clean: true,
+      subscriptions: [this.config.baseTopic + '/#'],
+      maxMessageTopics: (this.config.maxDevices ?? 2048) * 4 + 16,
+    });
+    this.removeMessageHandler = this.client.onMessage((messageArg) => this.receive(messageArg));
+    this.removeConnectionHandler = this.client.onConnectionState((stateArg) => {
+      const previous = this.snapshot();
+      this.connected = stateArg.connected;
+      if (!stateArg.connected) {
+        this.bridgeOnline = false;
+        this.bridgeReceived = false;
+        this.inventoryCurrent = false;
+        this.inventoryReceived = false;
+        this.availability.clear();
+        this.state.clear();
+        this.pendingMessages.clear();
+        if (stateArg.error) this.emitError('MQTT connection failed.');
+      }
+      this.emitChanges(previous);
+      this.resolveReady();
+    });
+  }
+
+  public async start(abortSignalArg?: AbortSignal): Promise<void> {
+    this.assertOpen(abortSignalArg);
+    if (this.started) throw new Error('Zigbee2MQTT runtime has already started.');
+    this.started = true;
+    if (abortSignalArg) {
+      const abort = (): void => { void this.destroy().catch(() => this.emitError('Zigbee2MQTT cancellation cleanup failed.')); };
+      abortSignalArg.addEventListener('abort', abort, { once: true });
+      this.removeSetupAbort = () => abortSignalArg.removeEventListener('abort', abort);
+    }
+    try {
+      await this.client.start(abortSignalArg);
+      this.assertOpen(abortSignalArg);
+      await this.waitForInventory(abortSignalArg);
+    } catch (error) {
+      try { await this.destroy(); }
+      catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Zigbee2MQTT setup and cleanup failed.'); }
+      throw error;
+    }
+  }
+
+  public isHealthy(): boolean {
+    return !this.destroyed && this.client.connected && this.bridgeOnline && this.inventoryCurrent;
+  }
+
+  public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.assertOpen(abortSignalArg);
+    return Zigbee2MqttMapper.toDevices(this.snapshot());
+  }
+
+  public async entities(): Promise<IIntegrationEntity[]> {
+    this.assertOpen();
+    return Zigbee2MqttMapper.toEntities(this.snapshot());
+  }
+
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.assertOpen(abortSignalArg);
+    if (typeof handlerArg !== 'function') throw new Error('Zigbee2MQTT subscription requires a callback.');
+    if (this.subscriptionCleanups.size >= 256) throw new Error('Zigbee2MQTT subscription limit exceeded.');
+    let released = false;
+    const cleanup = async (): Promise<void> => {
+      if (released) return;
+      released = true;
+      this.handlers.delete(listener);
+      this.subscriptionCleanups.delete(cleanup);
+      abortSignalArg?.removeEventListener('abort', abort);
+    };
+    const listener = { handler: handlerArg, cleanup };
+    this.handlers.add(listener);
+    const abort = (): void => { void cleanup(); };
+    this.subscriptionCleanups.add(cleanup);
+    abortSignalArg?.addEventListener('abort', abort, { once: true });
+    return cleanup;
+  }
+
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      this.assertOpen(abortSignalArg);
+      const request = zigbee2MqttRecord(requestArg);
+      const device = request && zigbee2MqttRecord(request.device);
+      const feature = request && zigbee2MqttRecord(request.feature);
+      if (!request || Object.keys(request).some((keyArg) => !['device', 'feature', 'value'].includes(keyArg)) ||
+        !device || device.integrationDomain !== this.domain || typeof device.id !== 'string' || !feature || typeof feature.id !== 'string') {
+        throw new Error('Zigbee2MQTT feature request requires a device owned by this domain.');
+      }
+      return await this.write(device.id, feature.id, request.value, abortSignalArg);
+    } catch (error) { return this.failure(error); }
+  }
+
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    try {
+      this.assertOpen();
+      const request = zigbee2MqttRecord(requestArg);
+      const target = request && zigbee2MqttRecord(request.target);
+      const data = request && zigbee2MqttRecord(request.data);
+      if (!request || Object.keys(request).some((keyArg) => !['domain', 'service', 'target', 'data'].includes(keyArg)) ||
+        request.domain !== this.domain || request.service !== 'set' || !target || !data ||
+        Object.keys(data).length !== 2 || !Object.hasOwn(data, 'property') || !Object.hasOwn(data, 'value') ||
+        typeof data.property !== 'string') throw new Error('Zigbee2MQTT set requires exactly property and value.');
+      if (Object.keys(target).length !== 1) throw new Error('Zigbee2MQTT set requires exactly one device or entity target.');
+      let selected: IZigbee2MqttDevice | undefined;
+      if (typeof target.deviceId === 'string') selected = this.findDevice(target.deviceId);
+      else if (typeof target.entityId === 'string' && target.entityId.endsWith('.' + data.property)) {
+        selected = this.findDevice(target.entityId.slice(0, -(data.property.length + 1)));
+      }
+      if (!selected) throw new Error('Zigbee2MQTT target is not in the current inventory.');
+      return await this.write(Zigbee2MqttMapper.deviceId(selected.ieeeAddress), data.property, data.value);
+    } catch (error) { return this.failure(error); }
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.destroyPromise) this.destroyPromise = this.destroyConnection();
+    return this.destroyPromise;
+  }
+
+  private async write(deviceIdArg: string, propertyArg: string, valueArg: unknown, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    this.assertOpen(abortSignalArg);
+    const device = this.findDevice(deviceIdArg);
+    const expose = device?.exposes.find((exposeArg) => exposeArg.property === propertyArg);
+    if (!device || !expose || !Zigbee2MqttMapper.available(this.snapshot([device]), device)) throw new Error('Zigbee2MQTT target is unavailable or not exposed.');
+    const value = Zigbee2MqttMapper.commandValue(expose, valueArg);
+    if (value === undefined) throw new Error('Zigbee2MQTT value is not permitted by the advertised expose.');
+    if (this.activeWrites >= 64) throw new Error('Zigbee2MQTT command admission limit exceeded.');
+    this.activeWrites++;
+    try {
+      const publication = this.client.publish({ topic: `${this.config.baseTopic}/${device.ieeeAddress}/set`, payload: { [expose.property]: value }, qos: 0, retain: false }, abortSignalArg);
+      this.pendingWrites.add(publication);
+      try { await publication; }
+      catch { throw new Error('Zigbee2MQTT command publication failed; its physical outcome is unconfirmed.'); }
+      finally { this.pendingWrites.delete(publication); }
+      return { success: true, data: { confirmation: 'mqtt-publish', physicalOutcome: 'unconfirmed' } };
+    } finally { this.activeWrites--; }
+  }
+
+  private receive(messageArg: IMqttMessage, replayArg = false): void {
+    if (this.destroyed || !messageArg.topic.startsWith(this.config.baseTopic + '/')) return;
+    const topic = messageArg.topic.slice(this.config.baseTopic.length + 1);
+    if (topic !== 'bridge/devices' && !topic.startsWith('bridge/') && !/\/(?:set|get)(?:\/|$)/.test(topic) &&
+      (!this.inventoryCurrent || !this.deviceForTopic(topic.replace(/\/availability$/, '')))) {
+      if (this.pendingMessages.size >= (this.config.maxDevices ?? 2048) * 2 && !this.pendingMessages.has(topic)) {
+        this.emitError('Zigbee2MQTT pending inventory message limit exceeded.');
+        return;
+      }
+      this.pendingMessages.set(topic, messageArg);
+      return;
+    }
+    if (topic !== 'bridge/devices' && topic !== 'bridge/state' && topic !== 'bridge/event' &&
+      !this.devicesByName.has(topic) && !this.devicesByIeee.has(topic) && !topic.endsWith('/availability')) return;
+    try {
+      const payload: unknown = typeof messageArg.payload === 'string' ? JSON.parse(messageArg.payload) : messageArg.payload;
+      const selectedDevice = topic.startsWith('bridge/') ? undefined : this.deviceForTopic(topic.replace(/\/availability$/, ''));
+      const scopedDevices = selectedDevice ? [selectedDevice] : undefined;
+      const previous = this.snapshot(scopedDevices);
+      if (topic === 'bridge/devices') this.applyInventory(payload);
+      else if (topic === 'bridge/state') {
+        const state = zigbee2MqttRecord(payload)?.state;
+        if (state !== 'online' && state !== 'offline') throw new Error('Invalid Zigbee2MQTT bridge state.');
+        this.bridgeReceived = true;
+        this.bridgeOnline = state === 'online';
+        if (!this.bridgeOnline) { this.availability.clear(); this.pendingMessages.clear(); this.inventoryCurrent = false; }
+      } else if (topic === 'bridge/event') this.applyBridgeEvent(payload);
+      else if (topic.endsWith('/availability')) {
+        const device = this.deviceForTopic(topic.slice(0, -'/availability'.length));
+        const state = zigbee2MqttRecord(payload)?.state;
+        if (device) {
+          if (state !== 'online' && state !== 'offline') throw new Error('Invalid Zigbee2MQTT device availability.');
+          this.availability.set(device.ieeeAddress, state === 'online');
+        }
+      } else {
+        const device = this.deviceForTopic(topic);
+        const payloadRecord = zigbee2MqttRecord(payload);
+        if (device && payloadRecord) this.applyState(device, payloadRecord, messageArg.timestamp ?? Date.now(), !messageArg.retain && !replayArg);
+        else if (device) throw new Error('Invalid Zigbee2MQTT device state.');
+      }
+      this.emitChanges(previous, scopedDevices);
+      this.resolveReady();
+      if (topic === 'bridge/devices') {
+        const pendingMessages = [...this.pendingMessages.values()];
+        this.pendingMessages.clear();
+        for (const message of pendingMessages) {
+          const pendingTopic = message.topic.slice(this.config.baseTopic.length + 1);
+          if (this.deviceForTopic(pendingTopic.replace(/\/availability$/, ''))) this.receive(message, true);
+        }
+      }
+    } catch {
+      if (topic === 'bridge/devices' || topic === 'bridge/state') {
+        const previous = this.snapshot();
+        this.inventoryCurrent = false;
+        if (topic === 'bridge/devices') this.inventoryReceived = false;
+        else { this.bridgeReceived = false; this.bridgeOnline = false; }
+        this.availability.clear();
+        this.state.clear();
+        this.pendingMessages.clear();
+        this.inventoryError = new Error('Zigbee2MQTT bridge inventory or state is malformed.');
+        this.emitChanges(previous);
+        for (const waiter of this.readyWaiters) waiter.reject(this.inventoryError);
+      } else if (topic.endsWith('/availability')) {
+        const previous = this.snapshot();
+        const device = this.deviceForTopic(topic.slice(0, -'/availability'.length));
+        if (device) this.availability.delete(device.ieeeAddress);
+        this.emitChanges(previous);
+      }
+      this.emitError('Invalid Zigbee2MQTT message.');
+    }
+  }
+
+  private applyInventory(payloadArg: unknown): void {
+    const devices = Zigbee2MqttMapper.parseInventory(payloadArg, this.config.maxDevices ?? 2048);
+    const next = new Map(devices.map((deviceArg) => [deviceArg.ieeeAddress, deviceArg]));
+    const previousDevices = this.devicesByIeee;
+    for (const [ieeeAddress, previous] of previousDevices) {
+      const device = next.get(ieeeAddress);
+      if (!device || device.friendlyName !== previous.friendlyName) {
+        this.availability.delete(ieeeAddress);
+        this.state.delete(ieeeAddress);
+      }
+    }
+    this.devicesByIeee = next;
+    this.devicesByName = new Map(devices.map((deviceArg) => [deviceArg.friendlyName, deviceArg]));
+    for (const [ieeeAddress, states] of this.state) {
+      const device = next.get(ieeeAddress);
+      for (const property of states.keys()) {
+        const expose = device?.exposes.find((exposeArg) => exposeArg.property === property && exposeArg.readable);
+        const previousExpose = previousDevices.get(ieeeAddress)?.exposes.find((exposeArg) => exposeArg.property === property);
+        if (!expose || JSON.stringify(previousExpose) !== JSON.stringify(expose)) states.delete(property);
+      }
+    }
+    this.inventoryCurrent = true;
+    this.inventoryReceived = true;
+    this.inventoryError = undefined;
+  }
+
+  private applyBridgeEvent(payloadArg: unknown): void {
+    const event = zigbee2MqttRecord(payloadArg);
+    const data = event && zigbee2MqttRecord(event.data);
+    if (event?.type !== 'device_leave' || typeof data?.ieee_address !== 'string') return;
+    const ieeeAddress = data.ieee_address.toLowerCase();
+    const device = this.devicesByIeee.get(ieeeAddress);
+    if (!device) return;
+    this.devicesByIeee.delete(ieeeAddress);
+    this.devicesByName.delete(device.friendlyName);
+    this.availability.delete(ieeeAddress);
+    this.state.delete(ieeeAddress);
+  }
+
+  private applyState(deviceArg: IZigbee2MqttDevice, payloadArg: Record<string, unknown>, timestampArg: number, liveEventArg: boolean): void {
+    let states = this.state.get(deviceArg.ieeeAddress);
+    if (!states) { states = new Map(); this.state.set(deviceArg.ieeeAddress, states); }
+    for (const expose of deviceArg.exposes) {
+      if (!expose.readable || !Object.hasOwn(payloadArg, expose.property)) continue;
+      const value = Zigbee2MqttMapper.reportedValue(expose, payloadArg[expose.property]);
+      if (value === undefined) { states.delete(expose.property); this.emitError('Zigbee2MQTT reported a value outside its expose type.'); continue; }
+      states.set(expose.property, { value, updatedAt: new Date(timestampArg).toISOString() });
+      if (liveEventArg && (expose.property === 'action' || expose.property.startsWith('action_'))) {
+        this.emit({ type: 'state_changed', integrationDomain: this.domain, deviceId: Zigbee2MqttMapper.deviceId(deviceArg.ieeeAddress),
+          entityId: Zigbee2MqttMapper.entityId(deviceArg.ieeeAddress, expose.property), data: { value }, timestamp: timestampArg });
+      }
+    }
+  }
+
+  private emitChanges(previousArg: IZigbee2MqttSnapshot, scopedDevicesArg?: IZigbee2MqttDevice[]): void {
+    const next = this.snapshot(scopedDevicesArg);
+    const previousDevices = new Map(previousArg.devices.map((deviceArg) => [deviceArg.ieeeAddress, deviceArg]));
+    for (const device of next.devices) {
+      if (!previousDevices.has(device.ieeeAddress)) this.emit({ type: 'device_added', integrationDomain: this.domain, deviceId: Zigbee2MqttMapper.deviceId(device.ieeeAddress), timestamp: Date.now() });
+    }
+    for (const device of previousArg.devices) {
+      if (!this.devicesByIeee.has(device.ieeeAddress)) this.emit({ type: 'device_removed', integrationDomain: this.domain, deviceId: Zigbee2MqttMapper.deviceId(device.ieeeAddress), timestamp: Date.now() });
+    }
+    const previous = new Map(Zigbee2MqttMapper.toEntities(previousArg).map((entityArg) => [entityArg.id, entityArg]));
+    const current = new Map(Zigbee2MqttMapper.toEntities(next).map((entityArg) => [entityArg.id, entityArg]));
+    for (const entity of current.values()) {
+      const before = previous.get(entity.id);
+      const event = { integrationDomain: this.domain, deviceId: entity.deviceId, entityId: entity.id, timestamp: Date.now() };
+      if (!before) this.emit({ ...event, type: 'entity_added', data: entity });
+      if (before?.available !== entity.available) this.emit({ ...event, type: 'availability_changed', data: { available: entity.available } });
+      const property = entity.attributes?.property;
+      const action = typeof property === 'string' && (property === 'action' || property.startsWith('action_'));
+      if (!action && (!before || before.state !== entity.state)) this.emit({ ...event, type: 'state_changed', data: entity });
+    }
+    for (const entity of previous.values()) {
+      if (!current.has(entity.id)) this.emit({ type: 'entity_removed', integrationDomain: this.domain, deviceId: entity.deviceId, entityId: entity.id, timestamp: Date.now() });
+    }
+  }
+
+  private snapshot(scopedDevicesArg?: IZigbee2MqttDevice[]): IZigbee2MqttSnapshot {
+    const devices = scopedDevicesArg ?? [...this.devicesByIeee.values()];
+    return {
+      devices, connected: this.connected && !this.destroyed,
+      bridgeOnline: this.bridgeOnline, inventoryCurrent: this.inventoryCurrent,
+      availability: new Map(devices.filter((deviceArg) => this.availability.has(deviceArg.ieeeAddress)).map((deviceArg) =>
+        [deviceArg.ieeeAddress, this.availability.get(deviceArg.ieeeAddress) === true])),
+      state: new Map(devices.map((deviceArg) => [deviceArg.ieeeAddress, new Map(this.state.get(deviceArg.ieeeAddress) ?? [])])),
+    };
+  }
+
+  private findDevice(idArg: string): IZigbee2MqttDevice | undefined {
+    return idArg.startsWith('zigbee2mqtt.') ? this.devicesByIeee.get(idArg.slice('zigbee2mqtt.'.length)) : undefined;
+  }
+
+  private deviceForTopic(topicArg: string): IZigbee2MqttDevice | undefined {
+    return this.devicesByName.get(topicArg) ?? this.devicesByIeee.get(topicArg.toLowerCase());
+  }
+
+  private waitForInventory(abortSignalArg?: AbortSignal): Promise<void> {
+    if (this.inventoryError) return Promise.reject(this.inventoryError);
+    if (this.inventoryReceived && this.bridgeReceived && this.client.connected) return Promise.resolve();
+    return new Promise<void>((resolve, reject) => {
+      const finish = (errorArg?: Error): void => {
+        clearTimeout(timer);
+        this.readyWaiters.delete(waiter);
+        abortSignalArg?.removeEventListener('abort', abort);
+        errorArg ? reject(errorArg) : resolve();
+      };
+      const waiter = { resolve: () => finish(), reject: (errorArg: Error) => finish(errorArg) };
+      const abort = (): void => finish(new DOMException('Zigbee2MQTT setup aborted.', 'AbortError'));
+      const timer = setTimeout(() => finish(new Error('Zigbee2MQTT retained bridge inventory timed out.')), this.config.inventoryTimeoutMs);
+      this.readyWaiters.add(waiter);
+      abortSignalArg?.addEventListener('abort', abort, { once: true });
+      if (abortSignalArg?.aborted) abort();
+    });
+  }
+
+  private resolveReady(): void {
+    if (this.inventoryReceived && this.bridgeReceived && this.client.connected) for (const waiter of [...this.readyWaiters]) waiter.resolve();
+  }
+
+  private async destroyConnection(): Promise<void> {
+    this.destroyed = true;
+    this.removeSetupAbort?.();
+    this.removeMessageHandler();
+    this.removeConnectionHandler();
+    for (const waiter of [...this.readyWaiters]) waiter.reject(new Error('Zigbee2MQTT runtime closed.'));
+    for (const cleanup of [...this.subscriptionCleanups]) await cleanup();
+    this.handlers.clear();
+    await this.client.destroy();
+    await Promise.allSettled([...this.pendingWrites]);
+    this.devicesByIeee.clear();
+    this.devicesByName.clear();
+    this.availability.clear();
+    this.state.clear();
+    this.pendingMessages.clear();
+  }
+
+  private assertOpen(abortSignalArg?: AbortSignal): void {
+    if (abortSignalArg?.aborted) throw new DOMException('Zigbee2MQTT operation aborted.', 'AbortError');
+    if (this.destroyed) throw new Error('Zigbee2MQTT runtime closed.');
+  }
+
+  private emit(eventArg: IIntegrationEvent): void {
+    for (const listener of [...this.handlers]) {
+      if (!this.handlers.has(listener)) continue;
+      try { listener.handler(structuredClone(eventArg)); }
+      catch {
+        // A consumer callback must not disconnect the transport shared by other subscribers.
+        void listener.cleanup();
+        this.emitError('Zigbee2MQTT subscriber callback failed.');
+      }
+    }
+  }
+
+  private emitError(messageArg: string): void {
+    this.emit({ type: 'error', integrationDomain: this.domain, data: { message: messageArg }, timestamp: Date.now() });
+  }
+
+  private failure(errorArg: unknown): IServiceCallResult {
+    return { success: false, error: errorArg instanceof Error ? errorArg.message : 'Zigbee2MQTT operation failed.' };
+  }
+}

package/ts/integrations/zigbee2mqtt/zigbee2mqtt.mapper.ts

@@ -0,0 +1,172 @@
+import type * as plugins from '../../plugins.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import type { IZigbee2MqttDevice, IZigbee2MqttExpose, IZigbee2MqttSnapshot, TZigbee2MqttPrimitive } from './zigbee2mqtt.types.js';
+import { zigbee2MqttPrimitive, zigbee2MqttRecord } from './zigbee2mqtt.validation.js';
+
+const specificTypes = new Set(['light', 'switch', 'fan', 'cover', 'lock', 'climate']);
+const forbiddenProperties = new Set(['__proto__', 'constructor', 'prototype', 'read', 'write', 'command', 'commands', 'get', 'set']);
+
+export class Zigbee2MqttMapper {
+  public static deviceId(ieeeAddressArg: string): string {
+    return `zigbee2mqtt.${ieeeAddressArg}`;
+  }
+
+  public static entityId(ieeeAddressArg: string, propertyArg: string): string {
+    return `${this.deviceId(ieeeAddressArg)}.${propertyArg}`;
+  }
+
+  public static parseInventory(payloadArg: unknown, maxDevicesArg: number): IZigbee2MqttDevice[] {
+    if (!Number.isSafeInteger(maxDevicesArg) || maxDevicesArg < 1 || maxDevicesArg > 10000) throw new Error('Invalid Zigbee2MQTT device limit.');
+    if (!Array.isArray(payloadArg) || payloadArg.length > maxDevicesArg) throw new Error('Zigbee2MQTT inventory is invalid or exceeds its device limit.');
+    const identities = new Set<string>();
+    const names = new Set<string>();
+    const devices = payloadArg.map((itemArg: unknown) => {
+      const item = zigbee2MqttRecord(itemArg);
+      if (!item || typeof item.ieee_address !== 'string' || !/^0x[0-9a-f]{16}$/i.test(item.ieee_address) ||
+        typeof item.friendly_name !== 'string' || !item.friendly_name || item.friendly_name.length > 256 ||
+        /[+#\u0000]/.test(item.friendly_name) || item.friendly_name.split('/').some((levelArg) => !levelArg) ||
+        item.friendly_name === 'bridge' || item.friendly_name.startsWith('bridge/') ||
+        /\/(?:availability|set|get)$/.test(item.friendly_name) || typeof item.supported !== 'boolean' ||
+        item.disabled !== undefined && typeof item.disabled !== 'boolean') throw new Error('Zigbee2MQTT inventory contains an invalid device identity.');
+      const ieeeAddress = item.ieee_address.toLowerCase();
+      if (identities.has(ieeeAddress) || names.has(item.friendly_name)) throw new Error('Zigbee2MQTT inventory contains ambiguous device identities.');
+      identities.add(ieeeAddress);
+      names.add(item.friendly_name);
+      const definition = zigbee2MqttRecord(item.definition);
+      if (item.supported && (!definition || !Array.isArray(definition.exposes))) throw new Error('A supported Zigbee2MQTT device is missing its advertised exposes.');
+      const normalized = this.parseExposes(definition?.exposes ?? []);
+      return {
+        ieeeAddress, friendlyName: item.friendly_name,
+        manufacturer: typeof definition?.vendor === 'string' ? definition.vendor.slice(0, 256) : undefined,
+        model: typeof definition?.model === 'string' ? definition.model.slice(0, 256) : undefined,
+        supported: item.supported, disabled: item.disabled === true || item.type === 'Coordinator',
+        ...normalized,
+      };
+    });
+    for (const device of devices) {
+      const addressAlias = device.friendlyName.toLowerCase();
+      if (identities.has(addressAlias) && addressAlias !== device.ieeeAddress) {
+        throw new Error('Zigbee2MQTT friendly name collides with another IEEE address.');
+      }
+    }
+    return devices;
+  }
+
+  public static toDevices(snapshotArg: IZigbee2MqttSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    return snapshotArg.devices.map((deviceArg) => ({
+      id: this.deviceId(deviceArg.ieeeAddress), integrationDomain: 'zigbee2mqtt', name: deviceArg.friendlyName,
+      manufacturer: deviceArg.manufacturer, model: deviceArg.model, protocol: 'zigbee',
+      online: this.available(snapshotArg, deviceArg),
+      features: deviceArg.exposes.map((exposeArg) => ({
+        id: exposeArg.property, name: exposeArg.name, capability: exposeArg.capability,
+        readable: exposeArg.readable, writable: exposeArg.writable && deviceArg.supported && !deviceArg.disabled,
+        unit: exposeArg.unit,
+      })),
+      state: deviceArg.exposes.filter((exposeArg) => exposeArg.readable).flatMap((exposeArg) => {
+        const state = snapshotArg.state.get(deviceArg.ieeeAddress)?.get(exposeArg.property);
+        return state ? [{ featureId: exposeArg.property, value: state.value, updatedAt: state.updatedAt }] : [];
+      }),
+      metadata: {
+        ieeeAddress: deviceArg.ieeeAddress, supported: deviceArg.supported, disabled: deviceArg.disabled,
+        unsupportedExposes: deviceArg.unsupportedExposes,
+        availability: snapshotArg.availability.has(deviceArg.ieeeAddress) ? snapshotArg.availability.get(deviceArg.ieeeAddress) ? 'online' : 'offline' : 'unknown',
+      },
+    }));
+  }
+
+  public static toEntities(snapshotArg: IZigbee2MqttSnapshot): IIntegrationEntity[] {
+    return snapshotArg.devices.flatMap((deviceArg) => deviceArg.exposes.map((exposeArg) => ({
+      id: this.entityId(deviceArg.ieeeAddress, exposeArg.property),
+      uniqueId: this.entityId(deviceArg.ieeeAddress, exposeArg.property),
+      integrationDomain: 'zigbee2mqtt', deviceId: this.deviceId(deviceArg.ieeeAddress),
+      name: `${deviceArg.friendlyName} ${exposeArg.name}`, platform: exposeArg.platform,
+      available: this.available(snapshotArg, deviceArg),
+      state: exposeArg.readable ? snapshotArg.state.get(deviceArg.ieeeAddress)?.get(exposeArg.property)?.value ?? null : null,
+      attributes: { property: exposeArg.property, readable: exposeArg.readable, writable: exposeArg.writable && deviceArg.supported && !deviceArg.disabled,
+        unit: exposeArg.unit, minimum: exposeArg.minimum, maximum: exposeArg.maximum, step: exposeArg.step,
+        values: exposeArg.values ? [...exposeArg.values] : undefined },
+    })));
+  }
+
+  public static available(snapshotArg: IZigbee2MqttSnapshot, deviceArg: IZigbee2MqttDevice): boolean {
+    return snapshotArg.connected && snapshotArg.bridgeOnline && snapshotArg.inventoryCurrent &&
+      deviceArg.supported && !deviceArg.disabled && snapshotArg.availability.get(deviceArg.ieeeAddress) === true;
+  }
+
+  public static reportedValue(exposeArg: IZigbee2MqttExpose, valueArg: unknown): TZigbee2MqttPrimitive | undefined {
+    if (!zigbee2MqttPrimitive(valueArg)) return undefined;
+    if (exposeArg.type === 'binary') return valueArg === exposeArg.valueOn ? true : valueArg === exposeArg.valueOff ? false : undefined;
+    if (exposeArg.type === 'numeric') return typeof valueArg === 'number' ? valueArg : undefined;
+    if (exposeArg.type === 'enum') return exposeArg.values?.includes(valueArg) ? valueArg : undefined;
+    return typeof valueArg === 'string' ? valueArg : undefined;
+  }
+
+  public static commandValue(exposeArg: IZigbee2MqttExpose, valueArg: unknown): TZigbee2MqttPrimitive | undefined {
+    if (!exposeArg.writable) return undefined;
+    if (exposeArg.type === 'binary') return typeof valueArg === 'boolean' ? valueArg ? exposeArg.valueOn : exposeArg.valueOff : undefined;
+    const value = this.reportedValue(exposeArg, valueArg);
+    if (exposeArg.type === 'numeric' && typeof value === 'number') {
+      if (exposeArg.minimum !== undefined && value < exposeArg.minimum || exposeArg.maximum !== undefined && value > exposeArg.maximum) return undefined;
+      if (exposeArg.step !== undefined) {
+        const steps = (value - (exposeArg.minimum ?? 0)) / exposeArg.step;
+        if (!Number.isFinite(steps) || Math.abs(steps - Math.round(steps)) > 1e-8) return undefined;
+      }
+    }
+    return value;
+  }
+
+  private static parseExposes(exposesArg: unknown): { exposes: IZigbee2MqttExpose[]; unsupportedExposes: number } {
+    if (!Array.isArray(exposesArg)) throw new Error('Invalid Zigbee2MQTT exposes.');
+    const exposes: IZigbee2MqttExpose[] = [];
+    let unsupportedExposes = 0;
+    let nodes = 0;
+    const walk = (itemsArg: unknown[], parentArg?: string): void => {
+      for (const raw of itemsArg) {
+        if (++nodes > 256) throw new Error('Zigbee2MQTT per-device expose limit exceeded.');
+        const expose = zigbee2MqttRecord(raw);
+        if (!expose) throw new Error('Invalid Zigbee2MQTT expose descriptor.');
+        if (typeof expose.type === 'string' && specificTypes.has(expose.type) && parentArg === undefined && Array.isArray(expose.features)) {
+          walk(expose.features, expose.type);
+          continue;
+        }
+        const parsed = this.parseExpose(expose, parentArg);
+        if (!parsed) { unsupportedExposes++; continue; }
+        if (exposes.some((itemArg) => itemArg.property === parsed.property)) throw new Error('Zigbee2MQTT expose property is ambiguous.');
+        exposes.push(parsed);
+      }
+    };
+    walk(exposesArg);
+    return { exposes, unsupportedExposes };
+  }
+
+  private static parseExpose(exposeArg: Record<string, unknown>, parentArg?: string): IZigbee2MqttExpose | undefined {
+    const type = exposeArg.type;
+    if (type !== 'binary' && type !== 'numeric' && type !== 'enum' && type !== 'text') return undefined;
+    if (typeof exposeArg.property !== 'string' || !/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/.test(exposeArg.property) || forbiddenProperties.has(exposeArg.property)) return undefined;
+    if (typeof exposeArg.access !== 'number' || !Number.isInteger(exposeArg.access) || exposeArg.access < 1 || exposeArg.access > 7 ||
+      typeof exposeArg.name !== 'string' || !exposeArg.name || exposeArg.name.length > 128) return undefined;
+    const readable = Boolean(exposeArg.access & 1);
+    const writable = Boolean(exposeArg.access & 2);
+    if (type === 'binary' && (!zigbee2MqttPrimitive(exposeArg.value_on) || !zigbee2MqttPrimitive(exposeArg.value_off) || exposeArg.value_on === exposeArg.value_off)) return undefined;
+    if (type === 'enum' && (!Array.isArray(exposeArg.values) || !exposeArg.values.length || exposeArg.values.length > 128 || !exposeArg.values.every(zigbee2MqttPrimitive))) return undefined;
+    for (const key of ['value_min', 'value_max', 'value_step']) {
+      if (exposeArg[key] !== undefined && (typeof exposeArg[key] !== 'number' || !Number.isFinite(exposeArg[key]))) return undefined;
+    }
+    const minimum = exposeArg.value_min as number | undefined;
+    const maximum = exposeArg.value_max as number | undefined;
+    const step = exposeArg.value_step as number | undefined;
+    if (minimum !== undefined && maximum !== undefined && minimum > maximum || step !== undefined && step <= 0) return undefined;
+    const capability = parentArg === 'light' || parentArg === 'switch' || parentArg === 'fan' || parentArg === 'cover' || parentArg === 'lock' || parentArg === 'climate' ? parentArg : 'sensor';
+    const platform = type === 'numeric' ? writable ? 'number' : 'sensor' : type === 'text' ? 'text' :
+      type === 'enum' ? writable ? 'select' : 'sensor' : writable ? parentArg === 'light' ? 'light' : 'switch' : 'binary_sensor';
+    return {
+      property: exposeArg.property, type, readable, writable, platform, capability,
+      name: typeof exposeArg.label === 'string' ? exposeArg.label.slice(0, 256) : exposeArg.name,
+      unit: typeof exposeArg.unit === 'string' ? exposeArg.unit.slice(0, 32) : undefined,
+      valueOn: type === 'binary' ? exposeArg.value_on as TZigbee2MqttPrimitive : undefined,
+      valueOff: type === 'binary' ? exposeArg.value_off as TZigbee2MqttPrimitive : undefined,
+      values: type === 'enum' ? [...exposeArg.values as TZigbee2MqttPrimitive[]] : undefined,
+      minimum, maximum, step,
+    };
+  }
+}

package/ts/integrations/zigbee2mqtt/zigbee2mqtt.types.ts

@@ -0,0 +1,63 @@
+import type { TEntityPlatform } from '../../core/types.js';
+import type * as plugins from '../../plugins.js';
+
+export interface IZigbee2MqttConfig {
+  host: string;
+  baseTopic: string;
+  port?: number;
+  protocol?: 'mqtt' | 'mqtts';
+  username?: string;
+  password?: string;
+  clientId?: string;
+  connectTimeoutMs?: number;
+  operationTimeoutMs?: number;
+  inventoryTimeoutMs?: number;
+  reconnectPeriodMs?: number;
+  maxDevices?: number;
+  maxPayloadBytes?: number;
+  maxBufferedBytes?: number;
+}
+
+export type TZigbee2MqttPrimitive = string | number | boolean;
+
+export interface IZigbee2MqttExpose {
+  property: string;
+  name: string;
+  type: 'binary' | 'numeric' | 'enum' | 'text';
+  readable: boolean;
+  writable: boolean;
+  platform: TEntityPlatform;
+  capability: plugins.shxInterfaces.data.TDeviceCapability;
+  unit?: string;
+  valueOn?: TZigbee2MqttPrimitive;
+  valueOff?: TZigbee2MqttPrimitive;
+  values?: TZigbee2MqttPrimitive[];
+  minimum?: number;
+  maximum?: number;
+  step?: number;
+}
+
+export interface IZigbee2MqttDevice {
+  ieeeAddress: string;
+  friendlyName: string;
+  manufacturer?: string;
+  model?: string;
+  supported: boolean;
+  disabled: boolean;
+  exposes: IZigbee2MqttExpose[];
+  unsupportedExposes: number;
+}
+
+export interface IZigbee2MqttReportedState {
+  value: TZigbee2MqttPrimitive;
+  updatedAt: string;
+}
+
+export interface IZigbee2MqttSnapshot {
+  devices: IZigbee2MqttDevice[];
+  connected: boolean;
+  bridgeOnline: boolean;
+  inventoryCurrent: boolean;
+  availability: ReadonlyMap<string, boolean>;
+  state: ReadonlyMap<string, ReadonlyMap<string, IZigbee2MqttReportedState>>;
+}