@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/denonavr/denonavr.types.ts

@@ -1,117 +1,57 @@
-export type TDenonavrZone = 'Main' | 'Zone2' | 'Zone3';
-
-export type TDenonavrPowerState = 'ON' | 'STANDBY' | 'OFF' | string;
-
-export type TDenonavrMediaState = 'on' | 'off' | 'playing' | 'paused' | 'stopped' | 'idle' | string;
-
-export type TDenonavrReceiverType = 'avr' | 'avr-x' | 'avr-x-2016' | string;
-
-export type TDenonavrCommand =
-  | 'turn_on'
-  | 'turn_off'
-  | 'volume_up'
-  | 'volume_down'
-  | 'set_volume'
-  | 'mute'
-  | 'select_source'
-  | 'play'
-  | 'pause'
-  | 'stop'
-  | 'play_pause'
-  | 'previous_track'
-  | 'next_track'
-  | 'get_command';
+export type TDenonavrModel = 'AVR-1913' | 'AVR-2113CI' | 'NR1605' | 'SR5009';
 
 export interface IDenonavrConfig {
-  host?: string;
-  port?: number;
+  homeId: string;
+  host: string;
+  descriptionUrl: string;
+  expectedUdn: string;
+  model: TDenonavrModel;
+  maximumVolumeDb: number;
   name?: string;
-  model?: string;
-  manufacturer?: string;
-  serialNumber?: string;
-  receiverType?: TDenonavrReceiverType;
-  descriptionPort?: number;
-  showAllSources?: boolean;
-  zone2?: boolean;
-  zone3?: boolean;
-  sourceMap?: Record<string, string>;
-  receiverInfo?: IDenonavrReceiverInfo;
-  zones?: IDenonavrZoneState[];
-  snapshot?: IDenonavrSnapshot;
-}
-
-export interface IHomeAssistantDenonavrConfig extends IDenonavrConfig {}
-
-export interface IDenonavrReceiverInfo {
-  host?: string;
   port?: number;
-  name?: string;
-  friendlyName?: string;
-  manufacturer?: string;
-  modelName?: string;
-  modelNumber?: string;
-  serialNumber?: string;
-  receiverType?: TDenonavrReceiverType;
-  receiverPort?: number;
-  presentationUrl?: string;
-  softwareVersion?: string;
+  timeoutMs?: number;
+  maxPendingOperations?: number;
+  maxDescriptionBytes?: number;
 }
 
-export interface IDenonavrMediaInfo {
-  title?: string;
-  artist?: string;
-  album?: string;
-  band?: string;
-  frequency?: string;
-  station?: string;
-  imageUrl?: string;
-  contentType?: string;
-}
+export interface IHomeAssistantDenonavrConfig extends IDenonavrConfig {}
 
-export interface IDenonavrZoneState {
-  zone: TDenonavrZone;
-  name?: string;
-  power?: TDenonavrPowerState;
-  state?: TDenonavrMediaState;
-  volumeDb?: number;
-  volumeLevel?: number;
-  muted?: boolean;
-  source?: string;
-  sourceList?: string[];
-  sourceMap?: Record<string, string>;
-  soundMode?: string;
-  soundModeRaw?: string;
-  soundModeList?: string[];
-  dynamicEq?: boolean;
-  ecoMode?: string;
-  media?: IDenonavrMediaInfo;
-  available?: boolean;
+export interface IDenonavrIdentity {
+  readonly udn: string;
+  readonly manufacturer: 'Denon' | 'Marantz';
+  readonly model: TDenonavrModel;
+  readonly name: string;
+  readonly serialNumber?: string;
+  readonly source: 'selected-upnp-description';
+  readonly observedAt: string;
 }
 
+/** Receiver settings are observations, not proof of electrical or acoustic effects. */
 export interface IDenonavrSnapshot {
-  receiverInfo: IDenonavrReceiverInfo;
-  zones: IDenonavrZoneState[];
-  events?: IDenonavrEvent[];
-  lastUpdated?: string;
+  readonly homeId: string;
+  readonly host: string;
+  readonly port: number;
+  readonly name: string;
+  readonly identity: IDenonavrIdentity;
+  readonly power: 'on' | 'standby';
+  readonly muted: boolean;
+  readonly volumeDb: number | null;
+  readonly input: string;
+  readonly observedInputs: readonly string[];
+  readonly maximumVolumeDb: number;
+  readonly observedAt: string;
 }
 
-export interface IDenonavrCommandRequest {
-  command: TDenonavrCommand;
-  zone?: TDenonavrZone;
-  source?: string;
-  volumeLevel?: number;
-  volumeDb?: number;
-  muted?: boolean;
-  path?: string;
-}
+export type TDenonavrControl =
+  | { feature: 'power'; value: boolean }
+  | { feature: 'muted'; value: boolean }
+  | { feature: 'volume_db'; value: number }
+  | { feature: 'input'; value: string };
 
-export interface IDenonavrEvent {
-  type: 'telnet' | 'http' | 'state';
-  zone?: TDenonavrZone;
-  event?: string;
-  parameter?: string;
-  command?: TDenonavrCommand;
-  timestamp: number;
+export interface IDenonavrEffectResult {
+  readonly dispatch: 'written';
+  readonly outcome: 'observed-target' | 'indeterminate';
+  readonly snapshot: IDenonavrSnapshot;
 }
 
 export interface IDenonavrSsdpRecord {
@@ -122,21 +62,18 @@ export interface IDenonavrSsdpRecord {
   upnp?: Record<string, string | undefined>;
 }
 
-export interface IDenonavrMdnsRecord {
-  name?: string;
-  type?: string;
-  host?: string;
-  port?: number;
-  txt?: Record<string, string | undefined>;
-}
-
 export interface IDenonavrManualEntry {
   host?: string;
-  port?: number;
+  descriptionUrl?: string;
+  expectedUdn?: string;
   id?: string;
   name?: string;
   manufacturer?: string;
   model?: string;
-  serialNumber?: string;
   metadata?: Record<string, unknown>;
 }
+
+export interface IDenonavrIntegrationOptions {
+  readonly homeId?: string;
+  readonly capacity?: number;
+}

package/ts/integrations/denonavr/denonavr.validation.ts

@@ -0,0 +1,87 @@
+import * as plugins from '../../plugins.js';
+import type { IDenonavrConfig, TDenonavrControl, TDenonavrModel } from './denonavr.types.js';
+
+export function denonavrRecord(value: unknown, allowed?: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new TypeError('DenonAVR input must be a plain data object.');
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== 'string' || (allowed && !allowed.includes(key)) || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError('DenonAVR input contains an unsupported field or accessor.');
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function denonavrText(value: unknown, label: string, maximum = 256): string {
+  if (typeof value !== 'string' || !value || value.length > maximum || value !== value.trim() || /[\p{Cc}\p{Cs}]/u.test(value)) {
+    throw new TypeError(`DenonAVR ${label} must be bounded text without control characters.`);
+  }
+  return value;
+}
+
+export function denonavrHost(value: unknown): string {
+  if (typeof value !== 'string' || plugins.net.isIP(value) !== 4) throw new TypeError('DenonAVR requires a selected private IPv4 address.');
+  const [first, second, , last] = value.split('.').map(Number);
+  if (!(first === 10 || first === 127 || (first === 172 && second >= 16 && second <= 31) || (first === 192 && second === 168)) || last === 0 || last === 255) {
+    throw new TypeError('DenonAVR requires a selected private or loopback host IPv4 address.');
+  }
+  return value;
+}
+
+export function denonavrModel(value: unknown): TDenonavrModel {
+  if (value !== 'AVR-1913' && value !== 'AVR-2113CI' && value !== 'NR1605' && value !== 'SR5009') throw new TypeError('DenonAVR model has no documented selected-receiver profile.');
+  return value;
+}
+
+export function denonavrUdn(value: unknown): string {
+  if (typeof value !== 'string' || !/^uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)) throw new TypeError('DenonAVR requires an exact UPnP UUID.');
+  return value.toLowerCase();
+}
+
+export function denonavrDescription(value: unknown, host: string): string {
+  const text = denonavrText(value, 'description URL', 2048);
+  const url = new URL(text);
+  if (url.protocol !== 'http:' || url.hostname !== host || url.username || url.password || url.search || url.hash || url.pathname === '/') {
+    throw new TypeError('DenonAVR description URL must select an HTTP path at the receiver IP without credentials, query or fragment.');
+  }
+  return url.href;
+}
+
+export function denonavrVolume(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < -79.5 || value > 18 || !Number.isInteger(value * 2)) {
+    throw new TypeError('DenonAVR absolute volume must be -79.5 through 18 dB in half-decibel steps.');
+  }
+  return value;
+}
+
+function integer(value: unknown, fallback: number, minimum: number, maximum: number): number {
+  if (value === undefined) return fallback;
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new RangeError('DenonAVR numeric bound is invalid.');
+  return value;
+}
+
+export function normalizeDenonavrConfig(value: unknown): Readonly<Required<Omit<IDenonavrConfig, 'name'>> & Pick<IDenonavrConfig, 'name'>> {
+  const config = denonavrRecord(value, ['homeId', 'host', 'descriptionUrl', 'expectedUdn', 'model', 'maximumVolumeDb', 'name', 'port', 'timeoutMs', 'maxPendingOperations', 'maxDescriptionBytes']);
+  const host = denonavrHost(config.host);
+  return Object.freeze({
+    homeId: denonavrText(config.homeId, 'home ID'), host,
+    descriptionUrl: denonavrDescription(config.descriptionUrl, host), expectedUdn: denonavrUdn(config.expectedUdn),
+    model: denonavrModel(config.model), maximumVolumeDb: denonavrVolume(config.maximumVolumeDb),
+    ...(config.name === undefined ? {} : { name: denonavrText(config.name, 'name', 128) }),
+    port: integer(config.port, 23, 1, 65535), timeoutMs: integer(config.timeoutMs, 5000, 1, 60000),
+    maxPendingOperations: integer(config.maxPendingOperations, 16, 1, 128), maxDescriptionBytes: integer(config.maxDescriptionBytes, 65536, 256, 1048576),
+  });
+}
+
+export function validateDenonavrControl(value: unknown): TDenonavrControl {
+  const control = denonavrRecord(value, ['feature', 'value']);
+  if (control.feature === 'power' && typeof control.value === 'boolean') return { feature: 'power', value: control.value };
+  if (control.feature === 'muted' && typeof control.value === 'boolean') return { feature: 'muted', value: control.value };
+  if (control.feature === 'volume_db') return { feature: 'volume_db', value: denonavrVolume(control.value) };
+  if (control.feature === 'input') return { feature: 'input', value: denonavrText(control.value, 'physical input', 25) };
+  throw new TypeError('DenonAVR supports one explicit power, mute, absolute volume or observed physical input control.');
+}

package/ts/integrations/esphome/esphome.classes.client.ts

@@ -1,10 +1,15 @@
 import * as plugins from '../../plugins.js';
-import type { IEsphomeClientCommand, IEsphomeCommandResult, IEsphomeConfig, IEsphomeEntityDescriptor, IEsphomeEntityState, IEsphomeEvent, IEsphomeSnapshot } from './esphome.types.js';
-import { esphomeDefaultNativeApiPort } from './esphome.types.js';
+import type { IEsphomeClientCommand, IEsphomeCommandResult, IEsphomeConfig, IEsphomeEntityDescriptor, IEsphomeEntityState, IEsphomeEvent, IEsphomeSnapshot, TEsphomeCredentials } from './esphome.types.js';
+import { captureEsphomeConfig, captureEsphomeCredentials, esphomeMac } from './esphome.validation.js';
 
 type TEsphomeEventHandler = (eventArg: IEsphomeEvent) => void;
 type TNativeClient = plugins.esphomeNativeApi.EspHomeClient;
 type TNativeEntity = plugins.esphomeNativeApi.Entity;
+interface IEsphomeCleanup {
+  readonly cleanup: () => void;
+  failed: boolean;
+  promise?: Promise<void>;
+}
 
 const readablePlatforms = new Set(['light', 'switch', 'fan', 'cover', 'climate', 'number', 'select', 'text', 'sensor', 'binary_sensor', 'text_sensor']);
 const writablePlatforms = new Set(['light', 'switch', 'fan', 'cover', 'number', 'select', 'text']);
@@ -12,12 +17,12 @@ const writablePlatforms = new Set(['light', 'switch', 'fan', 'cover', 'number',
 export class EsphomeClient {
   private readonly connection: EsphomeNativeApiConnection;
 
-  constructor(configArg: IEsphomeConfig, nativeClientArg?: TNativeClient) {
-    this.connection = new EsphomeNativeApiConnection(configArg, nativeClientArg);
+  constructor(configArg: IEsphomeConfig, nativeClientArg?: TNativeClient, credentialsArg: TEsphomeCredentials = {}) {
+    this.connection = new EsphomeNativeApiConnection(configArg, nativeClientArg, credentialsArg);
   }
 
-  public async connectLive(signalArg?: AbortSignal): Promise<void> {
-    await this.connection.connect(signalArg);
+  public connectLive(signalArg?: AbortSignal): Promise<void> {
+    return this.connection.connect(signalArg);
   }
 
   public isHealthy(): boolean {
@@ -28,16 +33,20 @@ export class EsphomeClient {
     return this.connection.getSnapshot();
   }
 
-  public onEvent(handlerArg: TEsphomeEventHandler): () => void {
-    return this.connection.onEvent(handlerArg);
+  public onEvent(handlerArg: TEsphomeEventHandler, signalArg?: AbortSignal): () => void {
+    return this.connection.onEvent(handlerArg, signalArg);
   }
 
   public async sendCommand(commandArg: IEsphomeClientCommand, signalArg?: AbortSignal): Promise<IEsphomeCommandResult> {
     return this.connection.sendCommand(commandArg, signalArg);
   }
 
-  public async destroy(): Promise<void> {
-    await this.connection.destroy();
+  public destroy(): Promise<void> {
+    return this.connection.destroy();
+  }
+
+  public retryCleanup(): Promise<void> {
+    return this.connection.retryCleanup();
   }
 }
 
@@ -48,83 +57,88 @@ export class EsphomeNativeApiConnection {
   private readonly setupTimeoutMs: number;
   private readonly commandTimeoutMs: number;
   private readonly requireEncryption: boolean;
+  private readonly config: IEsphomeConfig;
   private readonly handlers = new Set<TEsphomeEventHandler>();
-  private readonly subscriptions: Disposable[] = [];
+  private readonly cleanup = new Set<IEsphomeCleanup>();
+  private readonly operations = new Set<Promise<unknown>>();
   private readonly pendingCommands = new Set<string>();
   private readonly lifetime = new AbortController();
   private ready = false;
   private connecting = false;
   private destroyed = false;
+  private subscriptionsStarted = false;
+  private identityMismatch = false;
+  private closePromise?: Promise<void>;
+  private retryPromise?: Promise<void>;
 
-  constructor(configArg: IEsphomeConfig, nativeClientArg?: TNativeClient) {
-    const manual = configArg.manualEntries?.[0];
-    if (configArg.password || manual?.password) {
-      throw new Error('ESPHome legacy API password authentication is unsupported. Upgrade the device to ESPHome 2025.10 or newer and configure native API encryption.');
-    }
-    if (configArg.snapshot || configArg.entities || configArg.states || configArg.services || configArg.commandExecutor) {
-      throw new Error('ESPHome live setup does not accept injected snapshots, states, services, or command executors.');
-    }
-    if (configArg.manualEntries && configArg.manualEntries.length > 1) {
-      throw new Error('Configure each ESPHome native API device as a separate integration instance.');
-    }
-    this.host = (configArg.host || manual?.host || '').trim();
-    if (!this.host || /\s/.test(this.host)) {
-      throw new Error('ESPHome native API requires a valid host.');
-    }
-    this.port = configArg.port ?? manual?.port ?? esphomeDefaultNativeApiPort;
-    if (!Number.isInteger(this.port) || this.port < 1 || this.port > 65535) {
-      throw new Error('ESPHome native API port must be an integer from 1 through 65535.');
-    }
-    this.setupTimeoutMs = this.timeout(configArg.initialSnapshotTimeoutMs, 15000);
-    this.commandTimeoutMs = this.timeout(configArg.commandTimeoutMs, 5000);
-    const keys = [configArg.encryptionKey, configArg.noisePsk, manual?.encryptionKey, manual?.noisePsk].filter((valueArg): valueArg is string => valueArg !== undefined);
-    if (new Set(keys).size > 1) throw new Error('ESPHome encryption key configuration is conflicting.');
-    const key = keys[0];
-    if (key !== undefined && (!/^[A-Za-z0-9+/]{43}=$/.test(key) || Buffer.from(key, 'base64').length !== 32 || Buffer.from(key, 'base64').toString('base64') !== key)) {
-      throw new Error('ESPHome encryption key must be a canonical base64-encoded 32-byte key.');
-    }
-    this.requireEncryption = key !== undefined;
+  constructor(configArg: IEsphomeConfig, nativeClientArg?: TNativeClient, credentialsArg: TEsphomeCredentials = {}) {
+    this.config = captureEsphomeConfig(configArg);
+    const credentials = captureEsphomeCredentials(credentialsArg);
+    this.host = this.config.host;
+    this.port = this.config.port ?? 6053;
+    this.setupTimeoutMs = this.config.initialSnapshotTimeoutMs ?? 15000;
+    this.commandTimeoutMs = this.config.commandTimeoutMs ?? 5000;
+    this.requireEncryption = credentials.psk != null;
     this.native = nativeClientArg ?? new plugins.esphomeNativeApi.EspHomeClient({
       host: this.host,
       port: this.port,
-      psk: key,
-      serverName: configArg.deviceName || manual?.deviceName,
+      psk: credentials.psk,
+      serverName: this.config.deviceName,
       connectTimeoutMs: this.setupTimeoutMs,
     });
-    this.subscriptions.push(
-      this.native.on('telemetry', (eventArg) => {
-        this.refreshReadiness();
-        this.emit({ type: 'state_changed', entityId: this.eventEntityId(eventArg), data: eventArg });
-      }),
-      this.native.onHealthChange((healthArg) => {
-        if (healthArg.state === 'connected' && this.requireEncryption && !healthArg.encrypted) {
-          this.ready = false;
-          this.native.disconnect();
-          this.emit({ type: 'error', data: { message: 'ESPHome encryption is required; the plaintext session was rejected.' } });
-          return;
-        }
-        this.refreshReadiness();
-        this.emit({ type: 'availability_changed', data: { available: this.isHealthy() } });
-      }),
-    );
+    // Construction is inert: own the native client before invoking any subscription callbacks.
+    this.cleanup.add({ cleanup: () => this.native.disconnect(), failed: false });
+  }
+
+  private startSubscriptions(): void {
+    if (this.subscriptionsStarted) return;
+    this.subscriptionsStarted = true;
+    const telemetry = this.native.on('telemetry', (eventArg) => {
+      this.refreshReadiness();
+      if (!this.identityMismatch) this.emit({ type: 'state_changed', entityId: this.eventEntityId(eventArg), data: eventArg });
+    });
+    this.cleanup.add({ cleanup: () => telemetry[Symbol.dispose](), failed: false });
+    this.lifetime.signal.throwIfAborted();
+    const health = this.native.onHealthChange((healthArg) => {
+      if (healthArg.state === 'connected' && this.requireEncryption && !healthArg.encrypted) {
+        this.ready = false;
+        this.native.disconnect();
+        this.emit({ type: 'error', data: { message: 'ESPHome encryption is required; the plaintext session was rejected.' } });
+        return;
+      }
+      this.refreshReadiness();
+      this.emit({ type: 'availability_changed', data: { available: this.isHealthy() } });
+    });
+    this.cleanup.add({ cleanup: () => health[Symbol.dispose](), failed: false });
+    this.lifetime.signal.throwIfAborted();
   }
 
-  public async connect(signalArg?: AbortSignal): Promise<void> {
-    if (this.destroyed || this.connecting || this.isHealthy()) throw new Error('ESPHome connection is destroyed, already connecting, or already connected.');
+  public connect(signalArg?: AbortSignal): Promise<void> {
+    if (this.destroyed || this.connecting || this.isHealthy()) return Promise.reject(new Error('ESPHome connection is destroyed, already connecting, or already connected.'));
     this.connecting = true;
-    const signal = AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(this.setupTimeoutMs), ...(signalArg ? [signalArg] : [])]);
-    try {
-      signal.throwIfAborted();
-      await this.native.connect({ signal });
-      if (this.requireEncryption && !this.native.health().encrypted) throw new Error('ESPHome encryption is required; the plaintext session was rejected.');
-      if (this.native.deviceInfo()?.usesPassword) throw new Error('ESPHome legacy API password authentication is unsupported.');
-      await this.waitForInitialStates(signal);
-    } catch (error) {
-      await this.destroy();
-      throw error;
-    } finally {
-      this.connecting = false;
-    }
+    const operation = this.track(async () => {
+      const signal = AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(this.setupTimeoutMs), ...(signalArg ? [signalArg] : [])]);
+      try {
+        signal.throwIfAborted();
+        this.startSubscriptions();
+        await this.native.connect({ signal });
+        if (this.requireEncryption && !this.native.health().encrypted) throw new Error('ESPHome encryption is required; the plaintext session was rejected.');
+        if (this.native.deviceInfo()?.usesPassword) throw new Error('ESPHome legacy API password authentication is unsupported.');
+        this.assertIdentity();
+        await this.waitForInitialStates(signal);
+      } catch {
+        // SDK diagnostics may contain credentials; do not expose their messages or causes.
+        throw new Error('ESPHome native setup failed or was cancelled.');
+      } finally {
+        this.connecting = false;
+      }
+    });
+    // Join cleanup only after the tracked connect operation settles, so cleanup never awaits itself.
+    return operation.catch(async (errorArg: unknown) => {
+      try { await this.destroy(); }
+      catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'ESPHome setup and owned cleanup failed.'); }
+      throw errorArg;
+    });
   }
 
   public isHealthy(): boolean {
@@ -132,9 +146,11 @@ export class EsphomeNativeApiConnection {
   }
 
   public getSnapshot(): IEsphomeSnapshot {
+    if (this.identityMismatch) throw new Error('ESPHome selected device identity changed; native observations are unavailable.');
     const connected = this.isHealthy();
     const entities = this.native.entitiesByDevice(undefined).filter((entityArg) => readablePlatforms.has(entityArg.type));
     return {
+      homeId: this.config.homeId,
       host: this.host,
       port: this.port,
       connected,
@@ -155,13 +171,31 @@ export class EsphomeNativeApiConnection {
     };
   }
 
-  public onEvent(handlerArg: TEsphomeEventHandler): () => void {
+  public onEvent(handlerArg: TEsphomeEventHandler, signalArg?: AbortSignal): () => void {
     if (this.destroyed) throw new Error('ESPHome connection was destroyed.');
+    signalArg?.throwIfAborted();
+    let active = true;
+    const dispose = (): void => {
+      if (!active) return;
+      signalArg?.removeEventListener('abort', dispose);
+      this.handlers.delete(handlerArg);
+      active = false;
+      this.cleanup.delete(resource);
+    };
+    const resource: IEsphomeCleanup = { cleanup: dispose, failed: false };
+    // Own the handler and caller-signal listener before the foreign registration method.
+    this.cleanup.add(resource);
     this.handlers.add(handlerArg);
-    return () => this.handlers.delete(handlerArg);
+    signalArg?.addEventListener('abort', dispose, { once: true });
+    if (signalArg?.aborted) dispose();
+    return dispose;
   }
 
-  public async sendCommand(commandArg: IEsphomeClientCommand, signalArg?: AbortSignal): Promise<IEsphomeCommandResult> {
+  public sendCommand(commandArg: IEsphomeClientCommand, signalArg?: AbortSignal): Promise<IEsphomeCommandResult> {
+    return this.track(() => this.executeTrackedCommand(commandArg, signalArg));
+  }
+
+  private async executeTrackedCommand(commandArg: IEsphomeClientCommand, signalArg?: AbortSignal): Promise<IEsphomeCommandResult> {
     signalArg?.throwIfAborted();
     if (!this.isHealthy()) return { success: false, error: 'ESPHome is unavailable or has not received its authoritative initial states.' };
     const entity = this.native.entitiesByDevice(undefined).find((entityArg) => entityArg.key === commandArg.key && entityArg.type === commandArg.platform && (entityArg.deviceId ?? 0) === (commandArg.deviceId ?? 0));
@@ -174,22 +208,56 @@ export class EsphomeNativeApiConnection {
     try {
       const state = await this.executeCommand(entity, commandArg.payload, signalArg);
       return { success: true, data: structuredClone(state) };
-    } catch (error) {
-      return { success: false, error: error instanceof Error ? error.message : 'ESPHome command failed.' };
+    } catch {
+      return { success: false, error: 'ESPHome command failed or was cancelled; its physical effect is unknown.' };
     } finally {
       this.pendingCommands.delete(plugins.esphomeNativeApi.entityId(entity.type, entity.objectId));
     }
   }
 
-  public async destroy(): Promise<void> {
-    if (this.destroyed) return;
-    this.destroyed = true;
-    this.ready = false;
-    this.lifetime.abort(new Error('ESPHome connection was destroyed.'));
-    this.native.disconnect();
-    for (const subscription of this.subscriptions) subscription[Symbol.dispose]();
-    this.subscriptions.length = 0;
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.destroyed = true;
+      this.ready = false;
+      this.closePromise = Promise.resolve().then(() => this.drain(false));
+      this.lifetime.abort(new Error('ESPHome connection was destroyed.'));
+    }
+    return this.closePromise;
+  }
+
+  public retryCleanup(): Promise<void> {
+    if (!this.closePromise) throw new Error('ESPHome cleanup retry requires a closed client.');
+    if (!this.retryPromise) {
+      this.retryPromise = Promise.resolve().then(() => this.drain(true));
+      const settled = () => { this.retryPromise = undefined; };
+      void this.retryPromise.then(settled, settled);
+    }
+    return this.retryPromise;
+  }
+
+  private track<T>(workArg: () => Promise<T>): Promise<T> {
+    if (this.destroyed) return Promise.reject(new Error('ESPHome connection was destroyed.'));
+    // Store the actual operation before invoking native or consumer callbacks.
+    const operation = Promise.resolve().then(workArg);
+    this.operations.add(operation);
+    const settled = () => this.operations.delete(operation);
+    void operation.then(settled, settled);
+    return operation;
+  }
+
+  private async drain(retryArg: boolean): Promise<void> {
+    const cleanup = [...this.cleanup].reverse().map((resourceArg) => {
+      if (retryArg && resourceArg.failed) { resourceArg.promise = undefined; resourceArg.failed = false; }
+      resourceArg.promise ??= Promise.resolve().then(() => resourceArg.cleanup()).then(() => undefined, () => {
+        resourceArg.failed = true;
+        throw new Error('ESPHome owned resource cleanup failed.');
+      });
+      return resourceArg.promise;
+    });
+    const [results] = await Promise.all([Promise.allSettled(cleanup), Promise.allSettled([...this.operations])]);
     this.handlers.clear();
+    const failures = results.filter((resultArg) => resultArg.status === 'rejected');
+    if (failures.length) throw new AggregateError(failures.map(() => new Error('ESPHome owned resource cleanup failed.')), 'ESPHome cleanup failed; resources remain retained for explicit retry.');
   }
 
   private async executeCommand(entityArg: TNativeEntity, payloadArg: Record<string, unknown>, signalArg?: AbortSignal): Promise<unknown> {
@@ -253,14 +321,32 @@ export class EsphomeNativeApiConnection {
 
   private refreshReadiness(): void {
     const health = this.native.health();
-    this.ready = health.state === 'connected' && (!this.requireEncryption || health.encrypted) && this.native.entitiesByDevice(undefined).filter((entityArg) => readablePlatforms.has(entityArg.type)).every((entityArg) => this.native.latest(plugins.esphomeNativeApi.entityId(entityArg.type, entityArg.objectId)) != null);
+    if (health.state === 'connected') {
+      try { this.assertIdentity(); }
+      catch {
+        this.identityMismatch = true;
+        this.ready = false;
+        this.native.disconnect();
+        this.emit({ type: 'error', data: { message: 'ESPHome selected native device identity changed.' } });
+        return;
+      }
+    }
+    this.ready = !this.destroyed && !this.identityMismatch && health.state === 'connected' && (!this.requireEncryption || health.encrypted) && this.native.entitiesByDevice(undefined).filter((entityArg) => readablePlatforms.has(entityArg.type)).every((entityArg) => this.native.latest(plugins.esphomeNativeApi.entityId(entityArg.type, entityArg.objectId)) != null);
+  }
+
+  private assertIdentity(): void {
+    const info = this.native.deviceInfo();
+    if (!info || esphomeMac(info.macAddress) !== this.config.expectedMacAddress || info.name !== this.config.deviceName
+      || (this.config.expectedModel !== undefined && info.model !== this.config.expectedModel)) {
+      throw new Error('ESPHome native device identity does not match the selected endpoint.');
+    }
   }
 
   private entityId(entityArg: TNativeEntity): string {
     const macAddress = this.native.deviceInfo()?.macAddress?.toLowerCase().replace(/[^a-f0-9]/g, '');
     const identity = macAddress?.length === 12 ? macAddress : `${this.host}:${this.port}`;
     const digest = plugins.crypto.createHash('sha256').update(JSON.stringify([identity, entityArg.type, entityArg.key, entityArg.deviceId ?? 0])).digest('hex').slice(0, 24);
-    return `${entityArg.type}.esphome_${digest}`;
+    return `home.${encodeURIComponent(this.config.homeId)}.${entityArg.type}.esphome_${digest}`;
   }
 
   private eventEntityId(eventArg: plugins.esphomeNativeApi.TelemetryEvent): string | undefined {
@@ -285,12 +371,11 @@ export class EsphomeNativeApiConnection {
   }
 
   private emit(eventArg: IEsphomeEvent): void {
-    for (const handler of this.handlers) handler({ ...structuredClone(eventArg), timestamp: Date.now() });
-  }
-
-  private timeout(valueArg: number | undefined, defaultArg: number): number {
-    const value = valueArg ?? defaultArg;
-    if (!Number.isInteger(value) || value < 1 || value > 2147483647) throw new Error('ESPHome timeouts must be integers from 1 through 2147483647.');
-    return value;
+    const failures: unknown[] = [];
+    for (const handler of this.handlers) {
+      try { handler({ ...structuredClone(eventArg), timestamp: Date.now() }); }
+      catch (error) { failures.push(error); }
+    }
+    if (failures.length) throw new AggregateError(failures.map(() => new Error('ESPHome subscriber callback failed.')), 'ESPHome event callbacks failed.');
   }
 }