@smarthome.exchange/integrations 0.2.0 → 2.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,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;
   }
 }