@smarthome.exchange/integrations 0.1.0 → 1.0.0

package/ts/integrations/zha/zha.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 { IZhaManualEntry, IZhaMdnsRecord, IZhaUsbRecord, TZhaRadioType } from './zha.types.js';
+import { zhaBaudrate, zhaFlowControl, zhaRadioType, zhaResourcePath, zhaSocketPath, zhaString, zhaUsbId, zhaWildcardMatch } from './zha.discoveryvalidation.js';
 
 interface IZhaKnownUsbDevice {
   vid: string;
@@ -10,19 +11,17 @@ interface IZhaKnownUsbDevice {
   radioType?: TZhaRadioType;
 }
 
-const zhaZeroconfTypes = new Set([
-  '_zigbee-coordinator._tcp.local',
-  '_zigate-zigbee-gateway._tcp.local',
-  '_zigstar_gw._tcp.local',
-  '_uzg-01._tcp.local',
-  '_slzb-06._tcp.local',
-  '_xzg._tcp.local',
-  '_czc._tcp.local',
+const zhaZeroconfNames = new Map([
+  ['_zigbee-coordinator._tcp.local', '*'],
+  ['_zigate-zigbee-gateway._tcp.local', '*zigate*'],
+  ['_zigstar_gw._tcp.local', '*zigstar*'],
+  ['_uzg-01._tcp.local', 'uzg-01*'],
+  ['_slzb-06._tcp.local', 'slzb-06*'],
+  ['_xzg._tcp.local', 'xzg*'],
+  ['_czc._tcp.local', 'czc*'],
+  ['_esphomelib._tcp.local', 'tube*'],
 ]);
 
-const legacyZeroconfTypes = new Set(['_esphomelib._tcp.local']);
-const defaultZigbeeCoordinatorPort = 6638;
-
 const haManifestUsbDevices: IZhaKnownUsbDevice[] = [
   { vid: '10c4', pid: 'ea60', description: '*2652*', knownDevices: ['slae.sh cc2652rb stick'], radioType: 'znp' },
   { vid: '10c4', pid: 'ea60', description: '*slzb-07*', knownDevices: ['smlight slzb-07'], radioType: 'znp' },
@@ -41,24 +40,7 @@ const haManifestUsbDevices: IZhaKnownUsbDevice[] = [
   { vid: '10c4', pid: 'ea60', description: '*sonoff*lite*mg21*', knownDevices: ['sonoff zigbee dongle lite mg21'], radioType: 'ezsp' },
 ];
 
-const commonZigbeeUsbIds = new Set(haManifestUsbDevices.map((entryArg) => `${entryArg.vid}:${entryArg.pid}`));
-
-const zigbeeTextHints = [
-  'zigbee',
-  'conbee',
-  'sonoff',
-  'zigate',
-  'zigstar',
-  'tubeszb',
-  'slzb',
-  'cc2652',
-  'cc1352',
-  'efr32',
-  'ember',
-  'husbzb',
-  'skyconnect',
-  'zbt',
-];
+const notMatched = (reasonArg: string): IDiscoveryMatch => ({ matched: false, confidence: 'low', reason: reasonArg });
 
 export class ZhaUsbMatcher implements IDiscoveryMatcher<IZhaUsbRecord> {
   public id = 'zha-usb-match';
@@ -66,222 +48,89 @@ export class ZhaUsbMatcher implements IDiscoveryMatcher<IZhaUsbRecord> {
   public description = 'Recognize known USB Zigbee coordinators supported by ZHA.';
 
   public async matches(recordArg: IZhaUsbRecord): Promise<IDiscoveryMatch> {
-    const vid = this.normalizeUsbId(recordArg.vid);
-    const pid = this.normalizeUsbId(recordArg.pid);
-    const usbId = `${vid}:${pid}`;
-    const path = recordArg.path || recordArg.device;
-    const serialNumber = recordArg.serialNumber || recordArg.serial_number;
-    const text = this.recordText(recordArg);
-    const haMatch = haManifestUsbDevices.find((entryArg) => entryArg.vid === vid && entryArg.pid === pid && this.matchesManifestEntry(entryArg, text));
-    const idMatch = commonZigbeeUsbIds.has(usbId);
-    const textMatch = zigbeeTextHints.some((hintArg) => text.includes(hintArg));
-    const matched = Boolean(haMatch || idMatch || textMatch);
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'USB device is not a known ZHA Zigbee coordinator.' };
-    }
-    const radioType = haMatch?.radioType || this.guessRadioType(text, usbId);
+    const vid = zhaUsbId(recordArg.vid);
+    const pid = zhaUsbId(recordArg.pid);
+    const path = zhaResourcePath([recordArg.path, recordArg.device]);
+    const products = [zhaString(recordArg.description), zhaString(recordArg.product)].filter((valueArg): valueArg is string => valueArg !== undefined);
+    const haMatch = haManifestUsbDevices.find((entryArg) => entryArg.vid === vid && entryArg.pid === pid && products.some((productArg) => this.matchesManifestEntry(entryArg, productArg)));
+    if (!haMatch || !path || path.startsWith('socket://')) return notMatched('USB record does not identify a known Zigbee coordinator with a serial path.');
+    const product = products.find((productArg) => this.matchesManifestEntry(haMatch, productArg));
+    const serialNumber = zhaString(recordArg.serialNumber) || zhaString(recordArg.serial_number);
     return {
       matched: true,
-      confidence: haMatch ? 'certain' : idMatch ? 'high' : 'medium',
-      reason: haMatch ? 'USB record matches Home Assistant ZHA manifest USB metadata.' : 'USB record matches common Zigbee coordinator metadata.',
-      normalizedDeviceId: serialNumber || path || usbId,
+      confidence: 'high',
+      reason: 'USB product and identifiers match ZHA coordinator metadata; the radio is not probed.',
+      normalizedDeviceId: serialNumber || path,
       candidate: {
-        source: 'usb',
-        integrationDomain: 'zha',
-        id: serialNumber || path || usbId,
-        name: recordArg.description || recordArg.product || 'Zigbee coordinator',
-        manufacturer: recordArg.manufacturer || this.manufacturerFromText(text),
-        model: recordArg.description || recordArg.product || haMatch?.knownDevices?.[0],
-        serialNumber,
-        metadata: {
-          vid: recordArg.vid,
-          pid: recordArg.pid,
-          path,
-          radioPath: path,
-          serialNumber,
-          radioType,
-          baudrate: 115200,
-          flowControl: 'none',
-          haUsb: haMatch,
-        },
+        source: 'usb', integrationDomain: 'zha', id: serialNumber || path,
+        name: product || 'Zigbee coordinator', manufacturer: zhaString(recordArg.manufacturer),
+        model: product || haMatch.knownDevices?.[0], serialNumber,
+        metadata: { vid, pid, path, radioPath: path, serialNumber, radioType: haMatch.radioType, baudrate: 115200, flowControl: 'none' },
       },
     };
   }
 
-  private normalizeUsbId(valueArg?: string): string {
-    return (valueArg || '').replace(/^0x/i, '').toLowerCase().padStart(4, '0');
-  }
-
-  private recordText(recordArg: IZhaUsbRecord): string {
-    return [recordArg.manufacturer, recordArg.description, recordArg.product, recordArg.serialNumber, recordArg.serial_number]
-      .filter((valueArg): valueArg is string => typeof valueArg === 'string')
-      .join(' ')
-      .toLowerCase();
-  }
-
   private matchesManifestEntry(entryArg: IZhaKnownUsbDevice, textArg: string): boolean {
-    if (!entryArg.description && !entryArg.knownDevices?.length) {
-      return true;
-    }
-    const descriptionMatch = entryArg.description ? this.wildcardMatch(entryArg.description, textArg) : false;
-    const knownDeviceMatch = (entryArg.knownDevices || []).some((deviceArg) => textArg.includes(deviceArg.toLowerCase()));
-    return descriptionMatch || knownDeviceMatch;
-  }
-
-  private wildcardMatch(patternArg: string, valueArg: string): boolean {
-    const parts = patternArg.toLowerCase().split('*').filter(Boolean);
-    return parts.every((partArg) => valueArg.includes(partArg));
-  }
-
-  private guessRadioType(textArg: string, usbIdArg: string): TZhaRadioType | undefined {
-    if (textArg.includes('conbee')) {
-      return 'deconz';
-    }
-    if (textArg.includes('zigate')) {
-      return 'zigate';
-    }
-    if (textArg.includes('xbee')) {
-      return 'xbee';
-    }
-    if (textArg.includes('sonoff') && (textArg.includes('v2') || textArg.includes('mg21') || textArg.includes('mg24') || usbIdArg === '1a86:55d4')) {
-      return 'ezsp';
-    }
-    if (textArg.includes('efr32') || textArg.includes('ember') || textArg.includes('skyconnect') || textArg.includes('zbt')) {
-      return 'ezsp';
-    }
-    if (textArg.includes('cc2652') || textArg.includes('cc1352') || textArg.includes('zigstar') || textArg.includes('tubeszb') || textArg.includes('slzb')) {
-      return 'znp';
-    }
-    return undefined;
-  }
-
-  private manufacturerFromText(textArg: string): string {
-    if (textArg.includes('sonoff')) {
-      return 'SONOFF';
-    }
-    if (textArg.includes('conbee')) {
-      return 'dresden elektronik';
-    }
-    if (textArg.includes('zigate')) {
-      return 'ZiGate';
-    }
-    return 'Zigbee';
+    return Boolean(entryArg.description && zhaWildcardMatch(entryArg.description, textArg))
+      || (entryArg.knownDevices || []).some((deviceArg) => textArg.toLowerCase().includes(deviceArg.toLowerCase()));
   }
 }
 
 export class ZhaMdnsMatcher implements IDiscoveryMatcher<IZhaMdnsRecord> {
   public id = 'zha-mdns-match';
   public source = 'mdns' as const;
-  public description = 'Recognize network-attached Zigbee coordinators advertised for ZHA.';
+  public description = 'Recognize network-attached Zigbee coordinator advertisements.';
 
   public async matches(recordArg: IZhaMdnsRecord): Promise<IDiscoveryMatch> {
-    const type = this.normalizeType(recordArg.type);
+    const type = zhaString(recordArg.type)?.toLowerCase().replace(/\.$/, '') || '';
+    const name = zhaString(recordArg.name);
+    const pattern = zhaZeroconfNames.get(type);
+    const resourcePath = zhaSocketPath(recordArg.host ?? recordArg.hostname ?? recordArg.addresses?.[0], recordArg.port);
+    if (!pattern || !name || !zhaWildcardMatch(pattern, name) || !resourcePath) return notMatched('mDNS record lacks a recognized coordinator advertisement and usable endpoint.');
     const txt = recordArg.txt || recordArg.properties || {};
-    const text = [recordArg.name, recordArg.hostname, this.txt(txt, 'name'), this.txt(txt, 'radio_type')].filter(Boolean).join(' ').toLowerCase();
-    const isNativeType = zhaZeroconfTypes.has(type);
-    const isLegacyType = legacyZeroconfTypes.has(type) && (text.includes('tube') || text.includes('zigbee'));
-    const matched = isNativeType || isLegacyType || Boolean(this.txt(txt, 'radio_type') && this.txt(txt, 'serial_number'));
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'mDNS record is not a ZHA Zigbee coordinator advertisement.' };
-    }
-    const host = recordArg.host || recordArg.hostname || recordArg.addresses?.[0];
-    const port = recordArg.port || defaultZigbeeCoordinatorPort;
-    const radioType = this.txt(txt, 'radio_type') || this.guessRadioType(text, type);
-    const serialNumber = this.txt(txt, 'serial_number') || recordArg.hostname?.replace(/\.local\.?$/i, '');
+    const advertisedRadioType = zhaString(txt.radio_type ?? txt.RADIO_TYPE);
+    const radioType = advertisedRadioType ? zhaRadioType(advertisedRadioType) : undefined;
+    if (advertisedRadioType && !radioType) return notMatched('mDNS record advertises an unknown ZHA radio type.');
+    const host = resourcePath.slice('socket://'.length, resourcePath.lastIndexOf(':')).replace(/^\[([^\]]+)\]$/, '$1');
+    const port = Number(resourcePath.slice(resourcePath.lastIndexOf(':') + 1));
+    const serialNumber = zhaString(txt.serial_number ?? txt.SERIAL_NUMBER);
     return {
-      matched: true,
-      confidence: radioType && host ? 'certain' : host ? 'high' : 'medium',
-      reason: 'mDNS record matches ZHA network coordinator metadata.',
-      normalizedDeviceId: serialNumber || recordArg.name || host,
+      matched: true, confidence: 'high',
+      reason: 'mDNS service type and name match ZHA coordinator metadata; the radio is not probed.',
+      normalizedDeviceId: serialNumber || resourcePath,
       candidate: {
-        source: 'mdns',
-        integrationDomain: 'zha',
-        id: serialNumber || recordArg.name || host,
-        host,
-        port,
-        name: this.deviceName(recordArg, txt) || 'Zigbee coordinator',
-        manufacturer: 'Zigbee',
-        model: 'Network Zigbee coordinator',
-        serialNumber,
-        metadata: {
-          mdnsName: recordArg.name,
-          mdnsType: recordArg.type,
-          txt,
-          radioType,
-          radioPath: host ? `socket://${host}:${port}` : undefined,
-          socketUrl: host ? `socket://${host}:${port}` : undefined,
-          baudrate: 115200,
-          flowControl: 'none',
-        },
+        source: 'mdns', integrationDomain: 'zha', id: serialNumber || resourcePath, host, port,
+        name: zhaString(txt.name ?? txt.NAME) || name.split('._', 1)[0],
+        manufacturer: 'Zigbee', model: 'Network Zigbee coordinator', serialNumber,
+        metadata: { mdnsName: name, mdnsType: type, radioType, radioPath: resourcePath, socketUrl: resourcePath, baudrate: 115200, flowControl: 'none' },
       },
     };
   }
-
-  private txt(txtArg: Record<string, string | undefined>, keyArg: string): string | undefined {
-    return txtArg[keyArg] || txtArg[keyArg.toUpperCase()];
-  }
-
-  private normalizeType(valueArg?: string): string {
-    return (valueArg || '').toLowerCase().replace(/\.$/, '');
-  }
-
-  private deviceName(recordArg: IZhaMdnsRecord, txtArg: Record<string, string | undefined>): string | undefined {
-    return this.txt(txtArg, 'name') || recordArg.name?.split('._', 1)[0] || recordArg.hostname?.replace(/\.local\.?$/i, '');
-  }
-
-  private guessRadioType(textArg: string, typeArg: string): TZhaRadioType | undefined {
-    if (textArg.includes('zigate') || typeArg.includes('zigate')) {
-      return 'zigate';
-    }
-    if (textArg.includes('efr32') || textArg.includes('ezsp')) {
-      return 'ezsp';
-    }
-    if (textArg.includes('deconz') || textArg.includes('conbee')) {
-      return 'deconz';
-    }
-    if (textArg.includes('znp') || textArg.includes('zigstar') || textArg.includes('slzb') || textArg.includes('uzg') || textArg.includes('xzg')) {
-      return 'znp';
-    }
-    return undefined;
-  }
 }
 
 export class ZhaManualMatcher implements IDiscoveryMatcher<IZhaManualEntry> {
   public id = 'zha-manual-match';
   public source = 'manual' as const;
-  public description = 'Recognize manual ZHA radio setup entries.';
+  public description = 'Validate explicitly selected ZHA coordinator endpoints.';
 
   public async matches(inputArg: IZhaManualEntry): Promise<IDiscoveryMatch> {
-    const radioPath = inputArg.radioPath || inputArg.devicePath || inputArg.usbPath || inputArg.path || inputArg.socketUrl || (inputArg.host ? `socket://${inputArg.host}:${inputArg.port || defaultZigbeeCoordinatorPort}` : undefined);
-    const model = inputArg.model?.toLowerCase() || '';
-    const manufacturer = inputArg.manufacturer?.toLowerCase() || '';
-    const matched = Boolean(radioPath || inputArg.radioType || inputArg.metadata?.zha || inputArg.metadata?.zigbee || model.includes('zigbee') || manufacturer.includes('zigbee'));
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'Manual entry does not contain ZHA radio setup hints.' };
-    }
+    const path = zhaResourcePath([inputArg.radioPath, inputArg.devicePath, inputArg.usbPath, inputArg.path, inputArg.socketUrl], inputArg.host, inputArg.port);
+    const radioType = zhaRadioType(inputArg.radioType);
+    const model = zhaString(inputArg.model);
+    const manufacturer = zhaString(inputArg.manufacturer);
+    const explicitSelection = inputArg.radioPath !== undefined || inputArg.usbPath !== undefined || inputArg.socketUrl !== undefined
+      || radioType || inputArg.metadata?.zha === true || inputArg.metadata?.zigbee === true
+      || /zigbee/i.test(`${model || ''} ${manufacturer || ''}`);
+    const baudrate = inputArg.baudrate === undefined ? 115200 : zhaBaudrate(inputArg.baudrate);
+    const flowControl = inputArg.flowControl === undefined ? 'none' : zhaFlowControl(inputArg.flowControl);
+    if (!explicitSelection || !path || inputArg.radioType !== undefined && !radioType || !baudrate || flowControl === undefined) return notMatched('Manual entry lacks an explicit ZHA selection and valid coordinator settings.');
     return {
-      matched: true,
-      confidence: radioPath && inputArg.radioType ? 'high' : 'medium',
-      reason: 'Manual entry can start ZHA radio setup.',
-      normalizedDeviceId: inputArg.id || radioPath,
+      matched: true, confidence: 'medium', reason: 'Manual coordinator settings are valid; radio compatibility is not probed.',
+      normalizedDeviceId: zhaString(inputArg.id) || path,
       candidate: {
-        source: 'manual',
-        integrationDomain: 'zha',
-        id: inputArg.id || radioPath,
-        host: inputArg.host,
-        port: inputArg.port,
-        name: inputArg.name || 'Zigbee Home Automation',
-        manufacturer: inputArg.manufacturer || 'Zigbee',
-        model: inputArg.model || 'ZHA radio',
-        metadata: {
-          ...inputArg.metadata,
-          radioPath,
-          socketUrl: radioPath?.startsWith('socket://') ? radioPath : undefined,
-          radioType: inputArg.radioType,
-          baudrate: inputArg.baudrate,
-          flowControl: inputArg.flowControl,
-          snapshot: inputArg.snapshot,
-        },
+        source: 'manual', integrationDomain: 'zha', id: zhaString(inputArg.id) || path,
+        name: zhaString(inputArg.name) || 'Zigbee Home Automation', manufacturer: manufacturer || 'Zigbee', model: model || 'ZHA radio',
+        metadata: { radioPath: path, socketUrl: path.startsWith('socket://') ? path : undefined, radioType, baudrate, flowControl },
       },
     };
   }
@@ -289,27 +138,38 @@ export class ZhaManualMatcher implements IDiscoveryMatcher<IZhaManualEntry> {
 
 export class ZhaCandidateValidator implements IDiscoveryValidator {
   public id = 'zha-candidate-validator';
-  public description = 'Validate ZHA radio discovery candidates.';
+  public description = 'Validate coordinator source evidence and normalize its resource settings.';
 
   public async validate(candidateArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
+    if (candidateArg.integrationDomain !== undefined && candidateArg.integrationDomain !== 'zha') return notMatched('Candidate belongs to another integration.');
     const metadata = candidateArg.metadata || {};
-    const model = candidateArg.model?.toLowerCase() || '';
-    const manufacturer = candidateArg.manufacturer?.toLowerCase() || '';
-    const mdnsType = typeof metadata.mdnsType === 'string' ? metadata.mdnsType.toLowerCase().replace(/\.$/, '') : '';
-    const vid = typeof metadata.vid === 'string' ? metadata.vid.replace(/^0x/i, '').toLowerCase().padStart(4, '0') : '';
-    const pid = typeof metadata.pid === 'string' ? metadata.pid.replace(/^0x/i, '').toLowerCase().padStart(4, '0') : '';
-    const usbRecognized = Boolean(vid && pid && commonZigbeeUsbIds.has(`${vid}:${pid}`));
-    const hasRadioPath = typeof metadata.radioPath === 'string' || typeof metadata.socketUrl === 'string';
-    const textMatched = zigbeeTextHints.some((hintArg) => model.includes(hintArg) || manufacturer.includes(hintArg));
-    const matched = candidateArg.integrationDomain === 'zha' || usbRecognized || zhaZeroconfTypes.has(mdnsType) || Boolean(metadata.radioType || metadata.zha || metadata.zigbee || hasRadioPath && textMatched || textMatched);
-    return {
-      matched,
-      confidence: matched && candidateArg.integrationDomain === 'zha' && (hasRadioPath || metadata.radioType) ? 'certain' : matched && (usbRecognized || hasRadioPath) ? 'high' : matched ? 'medium' : 'low',
-      reason: matched ? 'Candidate has ZHA radio metadata.' : 'Candidate is not ZHA.',
-      candidate: matched ? candidateArg : undefined,
-      normalizedDeviceId: candidateArg.serialNumber || candidateArg.id || candidateArg.host,
-      metadata: matched ? { usbRecognized, hasRadioPath, radioType: metadata.radioType } : undefined,
-    };
+    const path = zhaResourcePath([metadata.radioPath, metadata.path, metadata.socketUrl], candidateArg.host, candidateArg.port);
+    if (!path) return notMatched('Candidate has no usable coordinator endpoint.');
+    const radioType = zhaRadioType(metadata.radioType);
+    const baudrate = metadata.baudrate === undefined ? undefined : zhaBaudrate(metadata.baudrate);
+    const flowControl = zhaFlowControl(metadata.flowControl);
+    if (metadata.radioType !== undefined && !radioType || metadata.baudrate !== undefined && !baudrate || metadata.flowControl !== undefined && flowControl === undefined) return notMatched('Candidate has invalid coordinator settings.');
+    if (candidateArg.source === 'usb') {
+      return new ZhaUsbMatcher().matches({
+        vid: zhaString(metadata.vid), pid: zhaString(metadata.pid), description: candidateArg.model || candidateArg.name,
+        manufacturer: candidateArg.manufacturer, serialNumber: candidateArg.serialNumber, path,
+      });
+    }
+    if (candidateArg.source === 'mdns') {
+      if (!path.startsWith('socket://')) return notMatched('Network coordinator requires a socket endpoint.');
+      return new ZhaMdnsMatcher().matches({
+        type: zhaString(metadata.mdnsType), name: zhaString(metadata.mdnsName), host: candidateArg.host, port: candidateArg.port,
+        txt: { radio_type: radioType, serial_number: candidateArg.serialNumber },
+      });
+    }
+    if (candidateArg.source === 'manual') {
+      if (candidateArg.integrationDomain !== 'zha' && !radioType && metadata.zha !== true && metadata.zigbee !== true && !/zigbee/i.test(`${candidateArg.model || ''} ${candidateArg.manufacturer || ''}`)) return notMatched('Manual candidate has no ZHA selection.');
+      return new ZhaManualMatcher().matches({
+        radioPath: path, radioType, baudrate, flowControl,
+        id: candidateArg.id, name: candidateArg.name, model: candidateArg.model, manufacturer: candidateArg.manufacturer,
+      });
+    }
+    return notMatched('ZHA coordinator discovery does not support this source.');
   }
 }
 

package/ts/integrations/zha/zha.discoveryvalidation.ts

@@ -0,0 +1,67 @@
+import * as plugins from '../../plugins.js';
+import type { TZhaFlowControl, TZhaRadioType } from './zha.types.js';
+
+export const zhaString = (valueArg: unknown, maximumLengthArg = 256): string | undefined => {
+  if (typeof valueArg !== 'string' || /[\u0000-\u001f\u007f]/.test(valueArg)) return undefined;
+  const value = valueArg.trim();
+  return value && value.length <= maximumLengthArg ? value : undefined;
+};
+
+export const zhaUsbId = (valueArg: unknown): string | undefined => {
+  const value = zhaString(valueArg)?.replace(/^0x/i, '').toLowerCase();
+  return value && /^[0-9a-f]{1,4}$/.test(value) ? value.padStart(4, '0') : undefined;
+};
+
+export const zhaRadioType = (valueArg: unknown): TZhaRadioType | undefined => {
+  const value = zhaString(valueArg)?.toLowerCase();
+  if (value === 'efr32') return 'ezsp';
+  if (value === 'ti_cc') return 'znp';
+  return value && ['ezsp', 'znp', 'deconz', 'xbee', 'zigate'].includes(value) ? value : undefined;
+};
+
+const zhaHost = (valueArg: unknown): string | undefined => {
+  const original = zhaString(valueArg, 253);
+  const bracketed = original?.startsWith('[') || original?.endsWith(']');
+  const value = original?.replace(/^\[([^\]]+)\]$/, '$1').replace(/\.$/, '').toLowerCase();
+  if (!value) return undefined;
+  if (bracketed) return plugins.net.isIP(value) === 6 ? value : undefined;
+  if (plugins.net.isIP(value)) return value;
+  if (/^[\d.]+$/.test(value)) return undefined;
+  return value.split('.').every((labelArg) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(labelArg)) ? value : undefined;
+};
+
+export const zhaSocketPath = (hostArg: unknown, portArg: unknown = 6638): string | undefined => {
+  const host = zhaHost(hostArg);
+  if (!host || typeof portArg !== 'number' || !Number.isInteger(portArg) || portArg < 1 || portArg > 65535) return undefined;
+  return `socket://${plugins.net.isIP(host) === 6 ? `[${host}]` : host}:${portArg}`;
+};
+
+export const zhaRadioPath = (valueArg: unknown): string | undefined => {
+  const value = zhaString(valueArg, 1024);
+  if (!value) return undefined;
+  if (/^COM[1-9]\d*$/i.test(value)) return value.toUpperCase();
+  if (value.startsWith('/dev/') && !/[?#\\]/.test(value) && value.split('/').slice(2).every((partArg) => partArg && partArg !== '.' && partArg !== '..')) return value;
+  const socket = /^socket:\/\/(\[[^\]]+\]|[^/:?#@\\\s]+):([0-9]+)$/i.exec(value);
+  return socket ? zhaSocketPath(socket[1], Number(socket[2])) : undefined;
+};
+
+export const zhaResourcePath = (pathsArg: unknown[], hostArg?: unknown, portArg?: unknown): string | undefined => {
+  const paths = pathsArg.filter((valueArg) => valueArg !== undefined).map(zhaRadioPath);
+  if (hostArg !== undefined) paths.push(zhaSocketPath(hostArg, portArg));
+  else if (portArg !== undefined) return undefined;
+  if (!paths.length || paths.some((valueArg) => valueArg === undefined)) return undefined;
+  return paths.every((valueArg) => valueArg === paths[0]) ? paths[0] : undefined;
+};
+
+export const zhaBaudrate = (valueArg: unknown): number | undefined => {
+  return typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg > 0 ? valueArg : undefined;
+};
+
+export const zhaFlowControl = (valueArg: unknown): TZhaFlowControl | undefined => {
+  return valueArg === 'none' || valueArg === 'hardware' || valueArg === 'software' || valueArg === null ? valueArg : undefined;
+};
+
+export const zhaWildcardMatch = (patternArg: string, textArg: string): boolean => {
+  const pattern = patternArg.toLowerCase().split('*').map((partArg) => partArg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*');
+  return new RegExp(`^${pattern}$`).test(textArg.toLowerCase());
+};

package/ts/integrations/zigbee2mqtt/index.ts

@@ -0,0 +1,5 @@
+export * from './zigbee2mqtt.classes.integration.js';
+export * from './zigbee2mqtt.classes.runtime.js';
+export * from './zigbee2mqtt.classes.configflow.js';
+export * from './zigbee2mqtt.mapper.js';
+export * from './zigbee2mqtt.types.js';

package/ts/integrations/zigbee2mqtt/readme.md

@@ -0,0 +1,40 @@
+# Zigbee2MQTT
+
+`Zigbee2MqttIntegration` connects directly to a configured MQTT broker and Zigbee2MQTT base topic. It reuses the package's native `MqttClient`; it does not require Home Assistant or connect to the Zigbee coordinator itself.
+
+```typescript
+const integration = new Zigbee2MqttIntegration();
+const runtime = await integration.setup({
+  host: 'broker.example.internal',
+  protocol: 'mqtts',
+  port: 8883,
+  baseTopic: 'home/zigbee2mqtt',
+  username: brokerUsername,
+  password: brokerPassword,
+}, { abortSignal: lifetimeController.signal });
+
+const [device] = await runtime.devices();
+const power = device?.features.find((feature) => feature.id === 'state');
+if (device?.online && power?.writable) {
+  await runtime.writeFeature?.({ device, feature: power, value: true });
+}
+await runtime.destroy();
+```
+
+The broker host and base topic are required explicitly. There is no automatic broker selection, injected inventory or fixture configuration in production. `mqtts` validates the broker certificate with Node's trusted certificate authorities; disabling certificate verification is not a supported option. The runtime holds supplied credentials in memory and does not persist them. The application must store and retrieve integration configuration through the public `NoSqlConfigStore` backed by `@lossless.org/client/nosqldb`, using its home scope and external encryption-key provider.
+
+Setup waits for received `BASE/bridge/devices` inventory and `BASE/bridge/state`. The inventory contains each device's actual `definition.exposes`; unsupported devices and coordinators cannot be operated. Device IDs use `zigbee2mqtt.0xIEEEADDRESS`, and feature IDs use the exact exposed property, including endpoint suffixes. Entity IDs combine those IDs. A friendly-name change keeps identity stable and discards state and availability learned through the former name.
+
+Binary, numeric, enum and text exposes are mapped, including primitive features inside advertised light, switch, fan, cover, lock and climate containers. Access bit 1 grants reported state and bit 2 grants writes. Binary features use normalized boolean values, translated into the advertised `value_on` and `value_off`. Numeric writes respect advertised minimum, maximum and step, enum writes accept advertised values only, and text values are limited to 1024 characters. Composite/list values, colors, schedules, numeric presets outside the normal range and binary toggles are unsupported. Their count is included in device metadata. Raw ZCL read/write/command fields are never exposed as controls.
+
+Device availability must be enabled in Zigbee2MQTT. An explicit received `{"state":"online"}` on a device's availability topic, current inventory, an online bridge and a ready MQTT connection are all required for control. Missing availability remains `unknown`; neither a sensor report nor a device announcement implies online status. Bridge shutdown and MQTT disconnect revoke admission and clear cached availability. Reconnect restores the owned subscription and requires freshly received inventory and bridge state before control resumes. Per-device state and availability reports received before the inventory are buffered within the configured limits and applied only to validated inventory members.
+
+`zigbee2mqtt.set` accepts exactly one target, either `deviceId` or `entityId`, and exactly `data: { property, value }`. The entity target must correspond to that property. Feature writes check the target's domain and resolve its current canonical feature, so caller-provided writable flags do not grant capabilities. Every command publishes one JSON property to `BASE/0xIEEEADDRESS/set`, using QoS 0 and `retain: false`. Commands are not retried. Success means the MQTT transport accepted publication and returns `physicalOutcome: 'unconfirmed'`; only subsequent device reports change state. MQTT publication does not prove physical execution.
+
+Subscriptions emit added/removed entities and devices, state changes and availability changes. Accepted live action reports are emitted once per report, including repeated identical actions; retained or pre-inventory action state does not replay physical events. Authoritative `device_leave` events remove a device immediately. Subscriber cancellation removes only that listener; a throwing listener is removed and produces an error for remaining subscribers. Runtime destruction and the setup context's lifetime abort cancel pending I/O, stop reconnect, remove callbacks and await socket cleanup.
+
+Connection, publication and inventory deadlines default to 7 seconds and are capped at 60 seconds. Inventory defaults to at most 2048 devices, 256 expose descriptors per device, 8 MiB per MQTT payload and 32 MiB total buffered MQTT data. Commands are limited to 64 in flight and listeners to 256. Unsupported bridge topics, including bridge configuration and logging, are never forwarded as entity attributes or errors.
+
+Groups, pairing, joining, binding, OTA, bridge configuration, network management, `/get` polling and Home Assistant discovery are outside this adapter. Tests use the real MQTT.js TCP parser against a local test broker; no hardware access is performed.
+
+Protocol references: [MQTT topics and messages](https://www.zigbee2mqtt.io/guide/usage/mqtt_topics_and_messages.html), [exposes and access masks](https://www.zigbee2mqtt.io/guide/usage/exposes.html), and [device availability](https://www.zigbee2mqtt.io/guide/configuration/device-availability.html).

package/ts/integrations/zigbee2mqtt/zigbee2mqtt.classes.configflow.ts

@@ -0,0 +1,26 @@
+import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import type { IZigbee2MqttConfig } from './zigbee2mqtt.types.js';
+import { zigbee2MqttConfig } from './zigbee2mqtt.validation.js';
+
+export class Zigbee2MqttConfigFlow implements IConfigFlow<IZigbee2MqttConfig> {
+  public async start(_candidateArg: IDiscoveryCandidate, _contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IZigbee2MqttConfig>> {
+    return {
+      kind: 'form', title: 'Connect Zigbee2MQTT',
+      description: 'Enter the broker and exact Zigbee2MQTT base topic. Enable device availability in Zigbee2MQTT before operating devices.',
+      fields: [
+        { name: 'host', label: 'Broker host', type: 'text', required: true },
+        { name: 'baseTopic', label: 'Zigbee2MQTT base topic', type: 'text', required: true },
+        { name: 'port', label: 'Broker port', type: 'number' },
+        { name: 'protocol', label: 'Protocol', type: 'select', options: [{ label: 'MQTT', value: 'mqtt' }, { label: 'MQTTS', value: 'mqtts' }] },
+        { name: 'username', label: 'Username', type: 'text' },
+        { name: 'password', label: 'Password', type: 'password' },
+      ],
+      submit: async (valuesArg) => {
+        try {
+          const config = zigbee2MqttConfig(valuesArg as unknown as IZigbee2MqttConfig);
+          return { kind: 'done', title: 'Zigbee2MQTT configured', config };
+        } catch { return { kind: 'error', error: 'Enter a valid broker, base topic and supported explicit configuration fields.' }; }
+      },
+    };
+  }
+}

package/ts/integrations/zigbee2mqtt/zigbee2mqtt.classes.integration.ts

@@ -0,0 +1,23 @@
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IIntegrationRuntime, IIntegrationSetupContext } from '../../core/types.js';
+import { Zigbee2MqttConfigFlow } from './zigbee2mqtt.classes.configflow.js';
+import { Zigbee2MqttRuntime } from './zigbee2mqtt.classes.runtime.js';
+import type { IZigbee2MqttConfig } from './zigbee2mqtt.types.js';
+
+export class Zigbee2MqttIntegration extends BaseIntegration<IZigbee2MqttConfig> {
+  public readonly domain = 'zigbee2mqtt';
+  public readonly displayName = 'Zigbee2MQTT';
+  public readonly status = 'control-runtime' as const;
+  public readonly discoveryDescriptor = new DiscoveryDescriptor({ integrationDomain: this.domain, displayName: this.displayName });
+  public readonly configFlow = new Zigbee2MqttConfigFlow();
+  public readonly metadata = { source: 'zigbee2mqtt', upstreamPath: 'Koenkk/zigbee2mqtt', iotClass: 'local_push' };
+
+  public async setup(configArg: IZigbee2MqttConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    const runtime = new Zigbee2MqttRuntime(configArg);
+    await runtime.start(contextArg.abortSignal);
+    return runtime;
+  }
+
+  public async destroy(): Promise<void> {}
+}