@smarthome.exchange/integrations 0.2.0 → 1.0.0

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

@@ -1,116 +1,296 @@
-import type { IEsphomeClientCommand, IEsphomeCommandResult, IEsphomeConfig, IEsphomeEvent, IEsphomeSnapshot } from './esphome.types.js';
-import { EsphomeMapper } from './esphome.mapper.js';
+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';
 
 type TEsphomeEventHandler = (eventArg: IEsphomeEvent) => void;
+type TNativeClient = plugins.esphomeNativeApi.EspHomeClient;
+type TNativeEntity = plugins.esphomeNativeApi.Entity;
+
+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']);
 
 export class EsphomeClient {
-  private readonly events: IEsphomeEvent[] = [];
-  private readonly eventHandlers = new Set<TEsphomeEventHandler>();
+  private readonly connection: EsphomeNativeApiConnection;
+
+  constructor(configArg: IEsphomeConfig, nativeClientArg?: TNativeClient) {
+    this.connection = new EsphomeNativeApiConnection(configArg, nativeClientArg);
+  }
+
+  public async connectLive(signalArg?: AbortSignal): Promise<void> {
+    await this.connection.connect(signalArg);
+  }
 
-  constructor(private readonly config: IEsphomeConfig) {}
+  public isHealthy(): boolean {
+    return this.connection.isHealthy();
+  }
 
   public async getSnapshot(): Promise<IEsphomeSnapshot> {
-    return EsphomeMapper.toSnapshot(this.config, undefined, this.events);
+    return this.connection.getSnapshot();
   }
 
   public onEvent(handlerArg: TEsphomeEventHandler): () => void {
-    this.eventHandlers.add(handlerArg);
-    return () => this.eventHandlers.delete(handlerArg);
-  }
-
-  public async sendCommand(commandArg: IEsphomeClientCommand): Promise<IEsphomeCommandResult> {
-    let result: IEsphomeCommandResult;
-    if (this.config.commandExecutor) {
-      result = this.commandResult(await this.config.commandExecutor(commandArg), commandArg);
-    } else {
-      result = {
-        success: false,
-        error: this.unsupportedLiveControlMessage(),
-        data: { command: commandArg },
-      };
-    }
-    this.emit({
-      type: result.success ? 'command_mapped' : 'command_failed',
-      command: commandArg,
-      data: result,
-      timestamp: Date.now(),
-      deviceId: this.stringValue(commandArg.deviceId),
-      entityId: commandArg.entityId,
-    });
-    return result;
+    return this.connection.onEvent(handlerArg);
   }
 
-  public async connectLive(): Promise<void> {
-    await new EsphomeNativeApiConnection(this.config).connect();
+  public async sendCommand(commandArg: IEsphomeClientCommand, signalArg?: AbortSignal): Promise<IEsphomeCommandResult> {
+    return this.connection.sendCommand(commandArg, signalArg);
   }
 
   public async destroy(): Promise<void> {
-    this.eventHandlers.clear();
+    await this.connection.destroy();
   }
+}
 
-  private emit(eventArg: IEsphomeEvent): void {
-    this.events.push(eventArg);
-    for (const handler of this.eventHandlers) {
-      handler(eventArg);
+export class EsphomeNativeApiConnection {
+  private readonly native: TNativeClient;
+  private readonly host: string;
+  private readonly port: number;
+  private readonly setupTimeoutMs: number;
+  private readonly commandTimeoutMs: number;
+  private readonly requireEncryption: boolean;
+  private readonly handlers = new Set<TEsphomeEventHandler>();
+  private readonly subscriptions: Disposable[] = [];
+  private readonly pendingCommands = new Set<string>();
+  private readonly lifetime = new AbortController();
+  private ready = false;
+  private connecting = false;
+  private destroyed = false;
+
+  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;
+    this.native = nativeClientArg ?? new plugins.esphomeNativeApi.EspHomeClient({
+      host: this.host,
+      port: this.port,
+      psk: key,
+      serverName: configArg.deviceName || manual?.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() } });
+      }),
+    );
   }
 
-  private commandResult(resultArg: unknown, commandArg: IEsphomeClientCommand): IEsphomeCommandResult {
-    if (this.isCommandResult(resultArg)) {
-      return resultArg;
+  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.');
+    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;
     }
-    return { success: true, data: resultArg ?? { command: commandArg } };
   }
 
-  private isCommandResult(valueArg: unknown): valueArg is IEsphomeCommandResult {
-    return typeof valueArg === 'object' && valueArg !== null && 'success' in valueArg;
+  public isHealthy(): boolean {
+    return !this.destroyed && this.ready && this.native.health().state === 'connected';
   }
 
-  private unsupportedLiveControlMessage(): string {
-    if (this.hasEncryptionKey()) {
-      return 'ESPHome live native API writes require protobuf framing plus Noise encryption support, which is not implemented. The mapped command was not sent.';
+  public getSnapshot(): IEsphomeSnapshot {
+    const connected = this.isHealthy();
+    const entities = this.native.entitiesByDevice(undefined).filter((entityArg) => readablePlatforms.has(entityArg.type));
+    return {
+      host: this.host,
+      port: this.port,
+      connected,
+      deviceInfo: {
+        ...structuredClone(this.native.deviceInfo()),
+        host: this.host,
+        port: this.port,
+        devices: this.native.subDevices().map((deviceArg) => ({ deviceId: deviceArg.id, name: deviceArg.name, areaId: deviceArg.areaId })),
+      },
+      entities: entities.map((entityArg) => this.entityDescriptor(entityArg)),
+      states: [...this.native.snapshot().values()].filter((eventArg) => readablePlatforms.has(eventArg.type)).map((eventArg): IEsphomeEntityState => ({
+        ...structuredClone(eventArg),
+        platform: eventArg.type,
+        entityId: this.eventEntityId(eventArg),
+        missingState: !connected || ('missingState' in eventArg && eventArg.missingState === true),
+      })),
+      events: [],
+    };
+  }
+
+  public onEvent(handlerArg: TEsphomeEventHandler): () => void {
+    if (this.destroyed) throw new Error('ESPHome connection was destroyed.');
+    this.handlers.add(handlerArg);
+    return () => this.handlers.delete(handlerArg);
+  }
+
+  public async sendCommand(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));
+    if (!entity || !writablePlatforms.has(entity.type) || this.pendingCommands.has(plugins.esphomeNativeApi.entityId(entity.type, entity.objectId))) {
+      return { success: false, error: 'ESPHome command target is unknown, unsupported, or already has a pending command.' };
     }
-    if (this.hasPassword()) {
-      return 'ESPHome live native API writes require protobuf framing plus legacy password login support, which is not implemented. The mapped command was not sent.';
+    const latest = this.native.latest(plugins.esphomeNativeApi.entityId(entity.type, entity.objectId));
+    if (!latest || ('missingState' in latest && latest.missingState)) return { success: false, error: 'ESPHome command target has no available authoritative state.' };
+    this.pendingCommands.add(plugins.esphomeNativeApi.entityId(entity.type, entity.objectId));
+    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.' };
+    } finally {
+      this.pendingCommands.delete(plugins.esphomeNativeApi.entityId(entity.type, entity.objectId));
     }
-    return 'ESPHome live native API writes require protobuf framing, which is not implemented. The mapped command was not sent.';
   }
 
-  private hasEncryptionKey(): boolean {
-    return Boolean(this.config.encryptionKey || this.config.noisePsk || this.config.manualEntries?.some((entryArg) => entryArg.encryptionKey || entryArg.noisePsk));
+  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;
+    this.handlers.clear();
   }
 
-  private hasPassword(): boolean {
-    return Boolean(this.config.password || this.config.manualEntries?.some((entryArg) => entryArg.password));
+  private async executeCommand(entityArg: TNativeEntity, payloadArg: Record<string, unknown>, signalArg?: AbortSignal): Promise<unknown> {
+    const options = { timeoutMs: this.commandTimeoutMs, signal: AbortSignal.any([this.lifetime.signal, ...(signalArg ? [signalArg] : [])]) };
+    switch (entityArg.type) {
+      case 'switch':
+      case 'light':
+      case 'fan': {
+        if (typeof payloadArg.state !== 'boolean' || Object.keys(payloadArg).some((keyArg) => keyArg !== 'state')) {
+          throw new Error('ESPHome power commands require a boolean state; additional light and fan settings are unsupported.');
+        }
+        const state = payloadArg.state;
+        const confirmation = { ...options, predicate: (eventArg: { state?: boolean; missingState?: boolean }) => eventArg.missingState !== true && eventArg.state === state };
+        if (entityArg.type === 'switch') return this.native.commandAndAwait(plugins.esphomeNativeApi.entityId('switch', entityArg.objectId), { state }, confirmation);
+        if (entityArg.type === 'light') return this.native.commandAndAwait(plugins.esphomeNativeApi.entityId('light', entityArg.objectId), { state }, confirmation);
+        return this.native.commandAndAwait(plugins.esphomeNativeApi.entityId('fan', entityArg.objectId), { state }, confirmation);
+      }
+      case 'number': {
+        const value = payloadArg.value;
+        if (typeof value !== 'number' || !Number.isFinite(value) || (entityArg.minValue !== undefined && value < entityArg.minValue) || (entityArg.maxValue !== undefined && value > entityArg.maxValue)) throw new Error('ESPHome number value is invalid or outside the advertised bounds.');
+        return this.native.commandAndAwait(plugins.esphomeNativeApi.entityId('number', entityArg.objectId), { state: value }, { ...options, predicate: (eventArg) => eventArg.missingState !== true && typeof eventArg.state === 'number' && Math.abs(eventArg.state - value) <= Math.max(0.000001, Math.abs(value) * 0.000001) });
+      }
+      case 'select': {
+        const value = payloadArg.option;
+        if (typeof value !== 'string' || !entityArg.options?.includes(value)) throw new Error('ESPHome select option is not advertised by the device.');
+        return this.native.commandAndAwait(plugins.esphomeNativeApi.entityId('select', entityArg.objectId), { state: value }, { ...options, predicate: (eventArg) => eventArg.missingState !== true && eventArg.state === value });
+      }
+      case 'text': {
+        const value = payloadArg.value;
+        if (typeof value !== 'string' || (entityArg.minLength !== undefined && value.length < entityArg.minLength) || (entityArg.maxLength !== undefined && value.length > entityArg.maxLength)) throw new Error('ESPHome text value is invalid or outside the advertised length bounds.');
+        return this.native.commandAndAwait(plugins.esphomeNativeApi.entityId('text', entityArg.objectId), { state: value }, { ...options, predicate: (eventArg) => eventArg.missingState !== true && eventArg.state === value });
+      }
+      case 'cover': {
+        const position = payloadArg.position;
+        if (!entityArg.supportsPosition || typeof position !== 'number' || !Number.isFinite(position) || position < 0 || position > 1) throw new Error('ESPHome cover requires a supported position from 0 through 1.');
+        return this.native.commandAndAwait(plugins.esphomeNativeApi.entityId('cover', entityArg.objectId), { position }, { ...options, predicate: (eventArg) => typeof eventArg.position === 'number' && Math.abs(eventArg.position - position) < 0.005 });
+      }
+      default: throw new Error('ESPHome entity does not support confirmed native commands.');
+    }
   }
 
-  private stringValue(valueArg: unknown): string | undefined {
-    if (typeof valueArg === 'string') {
-      return valueArg;
-    }
-    if (typeof valueArg === 'number' && Number.isFinite(valueArg)) {
-      return String(valueArg);
-    }
-    return undefined;
+  private entityDescriptor(entityArg: TNativeEntity): IEsphomeEntityDescriptor {
+    const info: Record<string, unknown> = { ...structuredClone(entityArg) };
+    return {
+      platform: entityArg.type,
+      key: entityArg.key,
+      entityId: this.entityId(entityArg),
+      objectId: entityArg.objectId,
+      name: entityArg.name,
+      deviceId: entityArg.deviceId,
+      writable: writablePlatforms.has(entityArg.type) && (entityArg.type !== 'cover' || entityArg.supportsPosition === true),
+      deviceClass: typeof info.deviceClass === 'string' ? info.deviceClass : undefined,
+      unitOfMeasurement: typeof info.unitOfMeasurement === 'string' ? info.unitOfMeasurement : undefined,
+      minValue: typeof info.minValue === 'number' ? info.minValue : undefined,
+      maxValue: typeof info.maxValue === 'number' ? info.maxValue : undefined,
+      supportsPosition: info.supportsPosition === true,
+      options: Array.isArray(info.options) ? info.options.filter((valueArg): valueArg is string => typeof valueArg === 'string') : undefined,
+      raw: info,
+    };
   }
-}
 
-export class EsphomeNativeApiConnection {
-  constructor(private readonly config: IEsphomeConfig) {}
+  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);
+  }
 
-  public async connect(): Promise<void> {
-    throw new Error(this.unsupportedMessage());
+  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}`;
   }
 
-  public async sendCommand(commandArg: IEsphomeClientCommand): Promise<void> {
-    void commandArg;
-    throw new Error(this.unsupportedMessage());
+  private eventEntityId(eventArg: plugins.esphomeNativeApi.TelemetryEvent): string | undefined {
+    const deviceId = 'deviceId' in eventArg ? eventArg.deviceId ?? 0 : 0;
+    const entity = this.native.entitiesByDevice(undefined).find((entityArg) => entityArg.type === eventArg.type && entityArg.key === eventArg.key && (entityArg.deviceId ?? 0) === deviceId);
+    return entity ? this.entityId(entity) : undefined;
   }
 
-  private unsupportedMessage(): string {
-    if (this.config.encryptionKey || this.config.noisePsk || this.config.manualEntries?.some((entryArg) => entryArg.encryptionKey || entryArg.noisePsk)) {
-      return 'Encrypted ESPHome native API uses Noise plus protobuf over TCP; live TCP support is intentionally not implemented in this dependency-free port.';
-    }
-    return 'ESPHome native API uses protobuf over TCP; live TCP support is intentionally not implemented in this dependency-free port.';
+  private async waitForInitialStates(signalArg: AbortSignal): Promise<void> {
+    this.refreshReadiness();
+    if (this.ready) return;
+    await new Promise<void>((resolveArg, rejectArg) => {
+      const cleanup = () => { unsubscribe(); signalArg.removeEventListener('abort', aborted); };
+      const aborted = () => { cleanup(); rejectArg(signalArg.reason); };
+      const unsubscribe = this.onEvent(() => {
+        if (this.ready) { cleanup(); resolveArg(); }
+        else if (this.native.health().state !== 'connected') { cleanup(); rejectArg(new Error('ESPHome disconnected before its initial states were received.')); }
+      });
+      signalArg.addEventListener('abort', aborted, { once: true });
+      if (signalArg.aborted) aborted();
+    });
+  }
+
+  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;
   }
 }

package/ts/integrations/esphome/esphome.classes.configflow.ts

@@ -8,12 +8,11 @@ export class EsphomeConfigFlow implements IConfigFlow<IEsphomeConfig> {
     return {
       kind: 'form',
       title: 'Connect ESPHome',
-      description: 'Configure an ESPHome native API device. Snapshot/manual data is supported; live protobuf control is reported explicitly if unavailable.',
+      description: 'Connect directly to the native API of an ESPHome 2025.10 or newer device. Use its 32-byte base64 encryption key when encryption is configured.',
       fields: [
         { name: 'host', label: 'Host', type: 'text', required: true },
         { name: 'port', label: 'Native API port', type: 'number' },
         { name: 'encryptionKey', label: 'Encryption key', type: 'password' },
-        { name: 'password', label: 'Legacy API password', type: 'password' },
       ],
       submit: async (valuesArg) => ({
         kind: 'done',
@@ -25,7 +24,6 @@ export class EsphomeConfigFlow implements IConfigFlow<IEsphomeConfig> {
           deviceName: this.stringValue(candidateArg.metadata?.deviceName),
           encryptionKey: this.stringValue(valuesArg.encryptionKey) || this.stringValue(candidateArg.metadata?.encryptionKey),
           noisePsk: this.stringValue(candidateArg.metadata?.noisePsk),
-          password: this.stringValue(valuesArg.password) || this.stringValue(candidateArg.metadata?.password),
           deviceInfo: {
             name: this.stringValue(candidateArg.metadata?.deviceName) || candidateArg.name,
             friendlyName: candidateArg.name,

package/ts/integrations/esphome/esphome.classes.integration.ts

@@ -1,11 +1,11 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { EsphomeClient } from './esphome.classes.client.js';
 import { EsphomeConfigFlow } from './esphome.classes.configflow.js';
 import { createEsphomeDiscoveryDescriptor } from './esphome.discovery.js';
 import { EsphomeMapper } from './esphome.mapper.js';
-import type { IEsphomeClientCommand, IEsphomeConfig } from './esphome.types.js';
+import type { IEsphomeConfig } from './esphome.types.js';
 
 export class EsphomeIntegration extends BaseIntegration<IEsphomeConfig> {
   public readonly domain = 'esphome';
@@ -14,41 +14,57 @@ export class EsphomeIntegration extends BaseIntegration<IEsphomeConfig> {
   public readonly discoveryDescriptor = createEsphomeDiscoveryDescriptor();
   public readonly configFlow = new EsphomeConfigFlow();
   public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/esphome',
-    upstreamDomain: 'esphome',
     integrationType: 'device',
     iotClass: 'local_push',
-    qualityScale: 'platinum',
-    requirements: [
-      'aioesphomeapi==44.21.0',
-      'esphome-dashboard-api==1.3.0',
-      'bleak-esphome==3.7.3',
-    ],
-    dependencies: ['assist_pipeline', 'bluetooth', 'intent', 'ffmpeg', 'http'],
-    afterDependencies: ['hassio', 'tag', 'usb', 'zeroconf'],
-    codeowners: ['@jesserockz', '@kbx81', '@bdraco'],
-    documentation: 'https://www.home-assistant.io/integrations/esphome',
+    documentation: 'https://esphome.io/components/api/',
+    nativeApiClient: 'esphome-client@2.0.0',
+    minimumFirmwareVersion: '2025.10',
     zeroconf: ['_esphomelib._tcp.local.'],
-    mqtt: ['esphome/discover/#'],
   };
+  private readonly runtimes = new Set<EsphomeRuntime>();
+  private readonly pendingClients = new Set<EsphomeClient>();
+  private destroyed = false;
 
   public async setup(configArg: IEsphomeConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new EsphomeRuntime(new EsphomeClient(configArg));
+    if (this.destroyed) throw new Error('ESPHome integration was destroyed.');
+    const client = new EsphomeClient(configArg);
+    this.pendingClients.add(client);
+    try {
+      await client.connectLive(contextArg.abortSignal);
+      if (this.destroyed) throw new Error('ESPHome integration was destroyed during setup.');
+      const runtime = new EsphomeRuntime(client, () => this.runtimes.delete(runtime));
+      this.runtimes.add(runtime);
+      return runtime;
+    } catch (error) {
+      await client.destroy();
+      throw error;
+    } finally {
+      this.pendingClients.delete(client);
+    }
   }
 
-  public async destroy(): Promise<void> {}
+  public async destroy(): Promise<void> {
+    this.destroyed = true;
+    await Promise.all([
+      ...[...this.runtimes].map((runtimeArg) => runtimeArg.destroy()),
+      ...[...this.pendingClients].map((clientArg) => clientArg.destroy()),
+    ]);
+  }
 }
 
 export class HomeAssistantEsphomeIntegration extends EsphomeIntegration {}
 
-class EsphomeRuntime implements IIntegrationRuntime {
-  public domain = 'esphome';
+export class EsphomeRuntime implements IIntegrationRuntime {
+  public readonly domain = 'esphome';
+
+  constructor(private readonly client: EsphomeClient, private readonly onDestroy?: () => void) {}
 
-  constructor(private readonly client: EsphomeClient) {}
+  public isHealthy(): boolean {
+    return this.client.isHealthy();
+  }
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    signalArg?.throwIfAborted();
     return EsphomeMapper.toDevices(await this.client.getSnapshot());
   }
 
@@ -56,62 +72,41 @@ class EsphomeRuntime implements IIntegrationRuntime {
     return EsphomeMapper.toEntities(await this.client.getSnapshot());
   }
 
-  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void): Promise<() => Promise<void>> {
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    signalArg?.throwIfAborted();
     const unsubscribe = this.client.onEvent((eventArg) => {
       handlerArg({
-        type: eventArg.type === 'command_mapped' ? 'state_changed' : 'error',
+        type: eventArg.type === 'state_changed' ? 'state_changed' : eventArg.type === 'availability_changed' ? 'availability_changed' : 'error',
         integrationDomain: 'esphome',
         deviceId: eventArg.deviceId,
         entityId: eventArg.entityId,
-        data: eventArg,
+        data: eventArg.data,
         timestamp: eventArg.timestamp || Date.now(),
       });
     });
-    await this.client.getSnapshot();
-    return async () => unsubscribe();
+    const cleanup = () => { unsubscribe(); signalArg?.removeEventListener('abort', cleanup); };
+    signalArg?.addEventListener('abort', cleanup, { once: true });
+    if (signalArg?.aborted) cleanup();
+    return async () => cleanup();
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const snapshot = await this.client.getSnapshot();
-    const command = requestArg.domain === 'esphome'
-      ? this.esphomeCommandFromService(requestArg)
-      : EsphomeMapper.commandForService(snapshot, requestArg);
-    if (!command) {
-      return { success: false, error: `ESPHome service ${requestArg.domain}.${requestArg.service} has no safe native command mapping.` };
-    }
-    const result = await this.client.sendCommand(command);
-    return { success: result.success, error: result.error, data: result.data };
+    if (!requestArg.target.entityId && !requestArg.target.deviceId) return { success: false, error: 'ESPHome service calls require an explicit entity or device target.' };
+    const command = EsphomeMapper.commandForService(await this.client.getSnapshot(), requestArg);
+    if (!command) return { success: false, error: `ESPHome service ${requestArg.domain}.${requestArg.service} has no unique supported native command target.` };
+    return this.client.sendCommand(command);
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    signalArg?.throwIfAborted();
+    if (requestArg.device.integrationDomain !== this.domain) return { success: false, error: 'ESPHome feature writes require an ESPHome device target.' };
+    const command = EsphomeMapper.commandForFeature(await this.client.getSnapshot(), requestArg.device.id, requestArg.feature.id, requestArg.value);
+    if (!command) return { success: false, error: 'ESPHome feature has no supported native command mapping.' };
+    return this.client.sendCommand(command, signalArg);
   }
 
-  private esphomeCommandFromService(requestArg: IServiceCallRequest): IEsphomeClientCommand | undefined {
-    if (requestArg.service === 'send_command' && this.isRecord(requestArg.data?.command)) {
-      return requestArg.data.command as unknown as IEsphomeClientCommand;
-    }
-    if (requestArg.service === 'execute_service' || requestArg.service === 'execute_action') {
-      const name = requestArg.data?.name;
-      if (typeof name !== 'string' || !name) {
-        return undefined;
-      }
-      return {
-        type: 'execute_service',
-        service: name,
-        payload: this.isRecord(requestArg.data?.data) ? requestArg.data.data : {},
-        target: requestArg.target,
-      };
-    }
-    return {
-      type: 'execute_service',
-      service: requestArg.service,
-      payload: requestArg.data || {},
-      target: requestArg.target,
-    };
-  }
-
-  private isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+  public async destroy(): Promise<void> {
+    await this.client.destroy();
+    this.onDestroy?.();
   }
 }

package/ts/integrations/esphome/esphome.discovery.ts

@@ -15,7 +15,7 @@ export class EsphomeMdnsMatcher implements IDiscoveryMatcher<IEsphomeMdnsRecord>
     const txt = recordArg.txt || recordArg.properties || {};
     const mac = this.normalizeMac(this.txt(txt, 'mac'));
     const deviceName = this.deviceName(recordArg, txt);
-    const matched = esphomeMdnsTypes.has(type) || Boolean(mac || this.txt(txt, 'api_encryption') || this.txt(txt, 'friendly_name'));
+    const matched = esphomeMdnsTypes.has(type);
     if (!matched) {
       return { matched: false, confidence: 'low', reason: 'mDNS record is not an ESPHome native API advertisement.' };
     }