@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/tplink/readme.md

@@ -0,0 +1,38 @@
+# TP-Link legacy Kasa
+
+`TplinkIntegration` provides a native local TCP runtime for the single relay advertised by legacy `IOT.SMARTPLUGSWITCH` devices. The integration delegates legacy XOR framing, same-connection identity and capability preflight, bounded operation queues, cancellation, and terminal socket cleanup to `@ecobridge.xyz/devicemanager` `KasaProtocol` (available from version `4.3.0`).
+
+```typescript
+import { TplinkIntegration } from '@smarthome.exchange/integrations';
+
+const integration = new TplinkIntegration();
+const runtime = await integration.setup({
+  homeId: 'your-home-id',
+  transport: 'legacy-kasa',
+  host: '192.168.1.40',
+  expectedDeviceId: '800611223344556677889900AABBCCDDEEFF001122',
+}, {});
+try {
+  const [device] = await runtime.devices();
+  const [entity] = await runtime.entities();
+  const result = await runtime.callService!({
+    domain: 'switch', service: 'turn_on', target: { entityId: entity.id },
+  });
+  console.log(result);
+  console.log((await runtime.devices())[0].state);
+} finally {
+  await integration.destroy();
+}
+```
+
+Configuration requires an explicit home ID, literal unicast IP address, expected legacy device ID, and `transport: 'legacy-kasa'`. Port defaults to `9999`; `timeoutMs` defaults to `5000` and covers queue admission, connection, identity preflight and the response. Resource limits are `maxResponseBytes` (default `65536`, range `128–1048576`) and `maxPendingOperations` (default `16`, range `1–128`). The deadline range is `1–30000` ms. Discovery advertisements are hints: actual legacy system information must verify identity and single-relay support before setup succeeds.
+
+The runtime exposes one writable `power` switch feature and one switch entity. IDs contain both the home and observed device identity. It admits only exact owned targets, `switch.turn_on`, `switch.turn_off`, or a boolean `power` feature write. Toggle, broadcast targets, additional service data and unsupported features are rejected before any write. `devices()` and `entities()` obtain fresh authoritative system information. Subscriptions observe these explicit reads; the integration does not claim a push protocol or run automatic polling.
+
+A successful write reports `outcome: 'accepted'` and `physicalStateConfirmed: false`. A protocol acknowledgment confirms acceptance only, never physical completion. Subsequent reads remain authoritative; there is no optimistic state update. Rejections report `not-sent`, `rejected` or `indeterminate`; an indeterminate effect must not be retried automatically. No command is retried or automatically reconnected. Destroy is terminal and idempotent, cancels queued and active work, drains owned sockets, and releases subscriptions.
+
+Legacy Kasa takes no credentials and performs no authentication. Its XOR obfuscation is not cryptographic encryption; an observed device-ID match does not authenticate the peer. Configure only an owner-controlled network endpoint. No secrets or filesystem application state are stored. If a caller provides a config store, it must be an encrypted `NoSqlConfigStore` scoped to the configured home and `tplink`; the integration does not own or close that store.
+
+Tapo, SMART/AES/KLAP, cloud login, bulbs, dimmer settings, energy-meter features, schedules, discovery broadcasts and child power strips are unsupported. These devices fail admission rather than falling back to snapshots or another transport. The existing `TplinkMapper` remains an offline snapshot mapping utility; supplying snapshots or `commandExecutor` to the native runtime is no longer supported. Migrate runtime configuration to the explicit native schema above.
+
+Verified against local TCP protocol fixtures only. Physical hardware, vendor credentials and firmware-specific behavior remain unverified. See the owning package's Kasa documentation and the [Home Assistant TP-Link integration](https://www.home-assistant.io/integrations/tplink/) for ecosystem coverage; that broader coverage does not define this runtime's admitted subset.

package/ts/integrations/tplink/tplink.classes.client.ts

@@ -1,93 +1,74 @@
-import type {
-  ITplinkClientCommand,
-  ITplinkCommandResult,
-  ITplinkConfig,
-  ITplinkEvent,
-  ITplinkSnapshot,
-} from './tplink.types.js';
-import { TplinkMapper } from './tplink.mapper.js';
-
-type TTplinkEventHandler = (eventArg: ITplinkEvent) => void;
+import * as plugins from '../../plugins.js';
+import type { ITplinkNativeConfig, ITplinkNativeSnapshot, ITplinkNativeWriteResult, TTplinkNativeEvent } from './tplink.native.types.js';
+import { normalizeTplinkNativeConfig } from './tplink.validation.js';
 
 export class TplinkClient {
-  private readonly events: ITplinkEvent[] = [];
-  private readonly eventHandlers = new Set<TTplinkEventHandler>();
-
-  constructor(private readonly config: ITplinkConfig) {}
-
-  public async getSnapshot(): Promise<ITplinkSnapshot> {
-    return TplinkMapper.toSnapshot(this.config, undefined, this.events);
-  }
+  readonly #config: Readonly<ITplinkNativeConfig>;
+  readonly #abortSignal?: AbortSignal;
+  readonly #protocol: plugins.ecobridgeDeviceManager.KasaProtocol;
+  readonly #handlers = new Set<(eventArg: TTplinkNativeEvent) => void>();
+  #healthy = false;
+  #closed = false;
+  #destroy?: Promise<void>;
 
-  public onEvent(handlerArg: TTplinkEventHandler): () => void {
-    this.eventHandlers.add(handlerArg);
-    return () => this.eventHandlers.delete(handlerArg);
+  constructor(configArg: ITplinkNativeConfig, abortSignalArg?: AbortSignal) {
+    this.#config = normalizeTplinkNativeConfig(configArg);
+    this.#abortSignal = abortSignalArg;
+    this.#protocol = new plugins.ecobridgeDeviceManager.KasaProtocol({
+      host: this.#config.host, port: this.#config.port, expectedDeviceId: this.#config.expectedDeviceId,
+      timeoutMs: this.#config.timeoutMs, maxResponseBytes: this.#config.maxResponseBytes,
+      maxPendingOperations: this.#config.maxPendingOperations, abortSignal: abortSignalArg,
+    });
   }
 
-  public async sendCommand(commandArg: ITplinkClientCommand): Promise<ITplinkCommandResult> {
-    this.emit({
-      type: 'command_mapped',
-      command: commandArg,
-      deviceId: commandArg.deviceId,
-      entityId: commandArg.entityId,
-      uniqueId: commandArg.uniqueId,
-      timestamp: Date.now(),
-    });
+  public get config(): Readonly<ITplinkNativeConfig> { return this.#config; }
 
-    if (this.config.commandExecutor) {
-      const result = this.commandResult(await this.config.commandExecutor(commandArg), commandArg);
-      this.emit({
-        type: result.success ? 'command_executed' : 'command_failed',
-        command: commandArg,
-        data: result,
-        deviceId: commandArg.deviceId,
-        entityId: commandArg.entityId,
-        uniqueId: commandArg.uniqueId,
-        timestamp: Date.now(),
-      });
-      return result;
-    }
+  public isHealthy(): boolean { return this.#healthy && !this.#closed && !this.#abortSignal?.aborted; }
 
-    const result: ITplinkCommandResult = {
-      success: false,
-      error: this.unsupportedLiveControlMessage(),
-      data: { command: commandArg },
-    };
-    this.emit({
-      type: 'command_failed',
-      command: commandArg,
-      data: result,
-      deviceId: commandArg.deviceId,
-      entityId: commandArg.entityId,
-      uniqueId: commandArg.uniqueId,
-      timestamp: Date.now(),
+  public async getSnapshot(abortSignalArg?: AbortSignal): Promise<ITplinkNativeSnapshot> {
+    let info: plugins.ecobridgeDeviceManager.IKasaSystemInfo;
+    try { info = await this.#protocol.getSystemInfo({ abortSignal: abortSignalArg }); }
+    catch (errorArg) { this.#healthy = false; throw errorArg; }
+    const snapshot: ITplinkNativeSnapshot = Object.freeze({
+      homeId: this.#config.homeId, deviceId: info.deviceId, name: info.alias, model: info.model,
+      macAddress: info.macAddress, softwareVersion: info.softwareVersion, hardwareVersion: info.hardwareVersion,
+      power: info.powerState, observedAt: new Date().toISOString(),
     });
-    return result;
+    this.#healthy = true;
+    for (const handler of this.#handlers) handler({ type: 'state', snapshot });
+    return snapshot;
   }
 
-  public async destroy(): Promise<void> {
-    this.eventHandlers.clear();
+  public onEvent(handlerArg: (eventArg: TTplinkNativeEvent) => void): () => void {
+    if (this.#closed || this.#abortSignal?.aborted) throw new Error('TP-Link client is closed.');
+    this.#handlers.add(handlerArg);
+    return () => { this.#handlers.delete(handlerArg); };
   }
 
-  private emit(eventArg: ITplinkEvent): void {
-    this.events.push(eventArg);
-    for (const handler of this.eventHandlers) {
-      handler(eventArg);
+  public async setPower(powerArg: boolean, abortSignalArg?: AbortSignal): Promise<ITplinkNativeWriteResult> {
+    try {
+      const acknowledgment = await this.#protocol.setPowerState(this.#config.expectedDeviceId, powerArg, { abortSignal: abortSignalArg });
+      return Object.freeze({
+        outcome: 'accepted', physicalStateConfirmed: false,
+        deviceId: acknowledgment.deviceId, requestedPowerState: acknowledgment.requestedPowerState,
+      });
+    } catch (errorArg) {
+      if (!(errorArg instanceof plugins.ecobridgeDeviceManager.KasaProtocolError)) throw errorArg;
+      if (errorArg.code !== 'DEVICE_ERROR' && errorArg.code !== 'ABORTED' && errorArg.code !== 'QUEUE_FULL') this.#healthy = false;
+      return Object.freeze({
+        outcome: errorArg.effectOutcome, physicalStateConfirmed: false, deviceId: this.#config.expectedDeviceId,
+        requestedPowerState: powerArg, errorCode: errorArg.code,
+      });
     }
   }
 
-  private commandResult(resultArg: unknown, commandArg: ITplinkClientCommand): ITplinkCommandResult {
-    if (this.isCommandResult(resultArg)) {
-      return resultArg;
+  public destroy(): Promise<void> {
+    if (!this.#destroy) {
+      this.#closed = true;
+      this.#healthy = false;
+      this.#handlers.clear();
+      this.#destroy = this.#protocol.close();
     }
-    return { success: true, data: resultArg ?? { command: commandArg } };
-  }
-
-  private isCommandResult(valueArg: unknown): valueArg is ITplinkCommandResult {
-    return typeof valueArg === 'object' && valueArg !== null && 'success' in valueArg;
-  }
-
-  private unsupportedLiveControlMessage(): string {
-    return 'TP-Link Kasa/Tapo live local writes require full python-kasa-equivalent protocol selection and encrypted transports (legacy IOT XOR plus SMART AES/KLAP). This dependency-free TypeScript port is snapshot/manual unless commandExecutor is provided.';
+    return this.#destroy;
   }
 }

package/ts/integrations/tplink/tplink.classes.configflow.ts

@@ -1,108 +1,56 @@
+import { NoSqlConfigStore } from '../../core/classes.configstore.js';
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
-import type { ITplinkConfig, ITplinkCredentials, ITplinkSnapshot } from './tplink.types.js';
-import { tplinkDefaultHttpPort } from './tplink.types.js';
-
-export class TplinkConfigFlow implements IConfigFlow<ITplinkConfig> {
-  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<ITplinkConfig>> {
-    void contextArg;
-    const metadata = candidateArg.metadata || {};
-    const host = candidateArg.host || this.stringValue(metadata.host) || '';
-    const model = candidateArg.model || this.stringValue(metadata.model) || '';
-    const alias = candidateArg.name || this.stringValue(metadata.alias) || this.stringValue(metadata.name) || '';
-    const requiresAuth = metadata.requiresAuth === true || metadata.encryptionType !== undefined || metadata.connectionParameters !== undefined;
-
+import { TplinkClient } from './tplink.classes.client.js';
+import type { ITplinkNativeConfig } from './tplink.native.types.js';
+import { normalizeTplinkNativeConfig, tplinkKeys, tplinkObject } from './tplink.validation.js';
+
+export class TplinkConfigFlow implements IConfigFlow<ITplinkNativeConfig> {
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<ITplinkNativeConfig>> {
+    const candidate = tplinkObject(candidateArg, 'TP-Link discovery candidate');
+    const host = typeof candidate.host === 'string' ? candidate.host : '';
+    const identity = typeof candidate.id === 'string' ? candidate.id : '';
+    if (contextArg.configStore !== undefined && !(contextArg.configStore instanceof NoSqlConfigStore)) {
+      throw new TypeError('TP-Link config flow requires an encrypted NoSqlConfigStore when a store is provided.');
+    }
+    const scope = contextArg.configStore?.getScope?.();
+    if (scope && scope.integrationDomain !== 'tplink') throw new TypeError('TP-Link config flow store has the wrong domain.');
     return {
-      kind: 'form',
-      title: 'Connect TP-Link Smart Home device',
-      description: requiresAuth
-        ? 'Provide the device host and TP-Link cloud credentials used by Kasa/Tapo devices. A snapshot can be supplied for read-only setup.'
-        : 'Provide the device host. Credentials are optional for legacy Kasa devices and required by many newer Kasa/Tapo devices. A snapshot can be supplied for read-only setup.',
+      kind: 'form', title: 'Connect legacy Kasa relay',
+      description: 'Verify one legacy IOT Kasa relay at an explicit IP address. Tapo, SMART/KLAP, bulbs and child power strips are unsupported. No credentials are accepted.',
       fields: [
-        { name: 'host', label: host ? `Host (${host})` : 'Host', type: 'text', required: true },
-        { name: 'port', label: `Port (${candidateArg.port || tplinkDefaultHttpPort})`, type: 'number' },
-        { name: 'username', label: 'TP-Link username', type: 'text', required: requiresAuth },
-        { name: 'password', label: 'TP-Link password', type: 'password', required: requiresAuth },
-        { name: 'alias', label: alias ? `Alias (${alias})` : 'Alias', type: 'text' },
-        { name: 'model', label: model ? `Model (${model})` : 'Model', type: 'text' },
-        { name: 'snapshotJson', label: 'Snapshot JSON', type: 'text' },
+        { name: 'homeId', label: scope ? `Home ID (${scope.homeId})` : 'Home ID', type: 'text', required: true },
+        { name: 'host', label: host ? `Device IP (${host})` : 'Device IP', type: 'text', required: true },
+        { name: 'expectedDeviceId', label: identity ? `Expected device ID (${identity})` : 'Expected device ID', type: 'text', required: true },
+        { name: 'port', label: 'Legacy TCP port (9999)', type: 'number' },
       ],
-      submit: async (valuesArg) => this.submit(candidateArg, valuesArg),
-    };
-  }
-
-  private async submit(candidateArg: IDiscoveryCandidate, valuesArg: Record<string, unknown>): Promise<IConfigFlowStep<ITplinkConfig>> {
-    const host = this.stringValue(valuesArg.host) || candidateArg.host;
-    if (!host) {
-      return { kind: 'error', title: 'Host required', error: 'TP-Link setup requires a host unless a config is created directly from a snapshot.' };
-    }
-
-    const snapshot = this.snapshotFromInput(valuesArg.snapshotJson);
-    if (snapshot instanceof Error) {
-      return { kind: 'error', title: 'Invalid snapshot', error: snapshot.message };
-    }
-
-    const username = this.stringValue(valuesArg.username);
-    const password = this.stringValue(valuesArg.password);
-    const credentials: ITplinkCredentials | undefined = username || password ? { username, password } : undefined;
-    const config: ITplinkConfig = {
-      host,
-      port: this.numberValue(valuesArg.port) || candidateArg.port || tplinkDefaultHttpPort,
-      alias: this.stringValue(valuesArg.alias) || candidateArg.name,
-      model: this.stringValue(valuesArg.model) || candidateArg.model,
-      macAddress: candidateArg.macAddress,
-      deviceId: candidateArg.id,
-      credentials,
-      snapshot,
-      connectionParameters: this.record(candidateArg.metadata?.connectionParameters)
-        ? candidateArg.metadata.connectionParameters
-        : undefined,
-      usesHttp: candidateArg.metadata?.usesHttp === true ? true : undefined,
-      metadata: {
-        discoverySource: candidateArg.source,
-        discoveryMetadata: candidateArg.metadata,
-        liveLocalWritesImplemented: false,
+      submit: async (valuesArg) => {
+        let client: TplinkClient | undefined;
+        try {
+          const values = tplinkObject(valuesArg, 'TP-Link config form');
+          tplinkKeys(values, ['homeId', 'host', 'expectedDeviceId', 'port']);
+          const config = normalizeTplinkNativeConfig({
+            homeId: typeof values.homeId === 'string' ? values.homeId : scope?.homeId ?? '',
+            transport: 'legacy-kasa', host: typeof values.host === 'string' ? values.host : host,
+            expectedDeviceId: typeof values.expectedDeviceId === 'string' ? values.expectedDeviceId : identity,
+            port: formPort(values.port, candidate.port),
+          });
+          if (scope && scope.homeId !== config.homeId) throw new TypeError('TP-Link config flow store has the wrong home.');
+          client = new TplinkClient(config);
+          await client.getSnapshot();
+          return { kind: 'done', title: 'Verified legacy Kasa relay', config };
+        } catch {
+          return { kind: 'error', title: 'Legacy Kasa verification failed',
+            error: 'Check the explicit IP, expected device identity, home scope and supported single-relay protocol.' };
+        } finally { await client?.destroy(); }
       },
     };
-
-    return {
-      kind: 'done',
-      title: 'TP-Link Smart Home device configured',
-      config,
-    };
-  }
-
-  private snapshotFromInput(valueArg: unknown): ITplinkSnapshot | undefined | Error {
-    const text = this.stringValue(valueArg);
-    if (!text) {
-      return undefined;
-    }
-    try {
-      const parsed = JSON.parse(text) as ITplinkSnapshot;
-      if (!parsed || !Array.isArray(parsed.devices)) {
-        return new Error('Snapshot JSON must include a devices array.');
-      }
-      return parsed;
-    } catch (error) {
-      return error instanceof Error ? error : new Error(String(error));
-    }
-  }
-
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-  }
-
-  private numberValue(valueArg: unknown): number | undefined {
-    if (typeof valueArg === 'number' && Number.isFinite(valueArg)) {
-      return valueArg;
-    }
-    if (typeof valueArg === 'string' && valueArg.trim()) {
-      const value = Number(valueArg);
-      return Number.isFinite(value) ? value : undefined;
-    }
-    return undefined;
-  }
-
-  private record(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
   }
 }
+
+const formPort = (valueArg: unknown, candidateArg: unknown): number | undefined => {
+  const value = valueArg === undefined || valueArg === '' ? candidateArg : valueArg;
+  if (value === undefined) return undefined;
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string' && /^\d{1,5}$/.test(value)) return Number(value);
+  throw new TypeError('TP-Link port must be an integer.');
+};

package/ts/integrations/tplink/tplink.classes.integration.ts

@@ -1,72 +1,150 @@
-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 { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { TplinkClient } from './tplink.classes.client.js';
 import { TplinkConfigFlow } from './tplink.classes.configflow.js';
 import { createTplinkDiscoveryDescriptor } from './tplink.discovery.js';
-import { TplinkMapper } from './tplink.mapper.js';
-import type { ITplinkConfig } from './tplink.types.js';
+import { TplinkNativeMapper } from './tplink.native.mapper.js';
+import type { ITplinkNativeConfig, ITplinkNativeSnapshot, ITplinkNativeWriteResult } from './tplink.native.types.js';
+import { normalizeTplinkNativeConfig } from './tplink.validation.js';
 
-export class TplinkIntegration extends BaseIntegration<ITplinkConfig> {
+export class TplinkIntegration extends BaseIntegration<ITplinkNativeConfig> {
   public readonly domain = 'tplink';
-  public readonly displayName = 'TP-Link Smart Home';
+  public readonly displayName = 'TP-Link legacy Kasa';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createTplinkDiscoveryDescriptor();
   public readonly configFlow = new TplinkConfigFlow();
   public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/tplink',
-    upstreamDomain: 'tplink',
-    documentation: 'https://www.home-assistant.io/integrations/tplink',
-    integrationType: 'device',
-    iotClass: 'local_polling',
-    qualityScale: 'platinum',
-    requirements: ['python-kasa[speedups]==0.10.2'],
-    dependencies: ['network', 'ffmpeg', 'stream'],
-    afterDependencies: [] as string[],
-    codeowners: ['@rytilahti', '@bdraco', '@sdb9696'],
-    dhcpDiscoveryPorts: [9999, 20002],
-    liveLocalWritesImplemented: false,
+    source: '@ecobridge.xyz/devicemanager', documentation: 'https://www.home-assistant.io/integrations/tplink',
+    integrationType: 'device', iotClass: 'local_polling', protocol: 'legacy-kasa',
+    supportedCapabilities: ['single-relay'], liveLocalWritesImplemented: true,
   };
+  readonly #clients = new Set<TplinkClient>();
+  readonly #runtimes = new Set<TplinkRuntime>();
+  #destroyed = false;
+  #destroy?: Promise<void>;
 
-  public async setup(configArg: ITplinkConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new TplinkRuntime(new TplinkClient(configArg));
+  public async setup(configArg: ITplinkNativeConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    if (this.#destroyed) throw new Error('TP-Link integration is destroyed.');
+    const config = normalizeTplinkNativeConfig(configArg);
+    if (contextArg.configStore !== undefined) {
+      if (!(contextArg.configStore instanceof NoSqlConfigStore)) throw new TypeError('TP-Link config store must be an encrypted NoSqlConfigStore.');
+      const scope = contextArg.configStore.getScope();
+      if (scope.homeId !== config.homeId || scope.integrationDomain !== this.domain) throw new TypeError('TP-Link config store scope does not match the configured home and domain.');
+    }
+    const client = new TplinkClient(config, contextArg.abortSignal);
+    this.#clients.add(client);
+    try {
+      const identity = await client.getSnapshot(contextArg.abortSignal);
+      if (this.#destroyed || contextArg.abortSignal?.aborted) throw new Error('TP-Link setup was canceled.');
+      const runtime = new TplinkRuntime(client, identity, () => { this.#runtimes.delete(runtime); });
+      this.#runtimes.add(runtime);
+      this.#clients.delete(client);
+      return runtime;
+    } catch (errorArg) {
+      try { await client.destroy(); }
+      catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'TP-Link setup and cleanup failed.'); }
+      finally { this.#clients.delete(client); }
+      throw errorArg;
+    }
   }
 
-  public async destroy(): Promise<void> {}
+  public destroy(): Promise<void> {
+    if (!this.#destroy) {
+      this.#destroyed = true;
+      this.#destroy = Promise.allSettled([
+        ...[...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()),
+        ...[...this.#clients].map((clientArg) => clientArg.destroy()),
+      ]).then((resultsArg) => {
+        this.#clients.clear();
+        this.#runtimes.clear();
+        const errors = resultsArg.flatMap((resultArg) => resultArg.status === 'rejected' ? [resultArg.reason as unknown] : []);
+        if (errors.length) throw new AggregateError(errors, 'TP-Link integration cleanup failed.');
+      });
+    }
+    return this.#destroy;
+  }
 }
 
 export class HomeAssistantTplinkIntegration extends TplinkIntegration {}
 
 class TplinkRuntime implements IIntegrationRuntime {
-  public domain = 'tplink';
-
-  constructor(private readonly client: TplinkClient) {}
+  public readonly domain = 'tplink';
+  readonly #client: TplinkClient;
+  readonly #identity: ITplinkNativeSnapshot;
+  readonly #release: () => void;
+  readonly #subscriptions = new Set<() => void>();
+  #destroy?: Promise<void>;
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return TplinkMapper.toDevices(await this.client.getSnapshot());
+  constructor(clientArg: TplinkClient, identityArg: ITplinkNativeSnapshot, releaseArg: () => void) {
+    this.#client = clientArg;
+    this.#identity = identityArg;
+    this.#release = releaseArg;
   }
 
-  public async entities(): Promise<IIntegrationEntity[]> {
-    return TplinkMapper.toEntities(await this.client.getSnapshot());
+  public isHealthy(): boolean { return this.#client.isHealthy(); }
+
+  public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return TplinkNativeMapper.toDevices(await this.#client.getSnapshot(abortSignalArg));
   }
 
-  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void): Promise<() => Promise<void>> {
-    const unsubscribe = this.client.onEvent((eventArg) => handlerArg(TplinkMapper.toIntegrationEvent(eventArg)));
-    await this.client.getSnapshot();
-    return async () => unsubscribe();
+  public async entities(): Promise<IIntegrationEntity[]> { return TplinkNativeMapper.toEntities(await this.#client.getSnapshot()); }
+
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    abortSignalArg?.throwIfAborted();
+    const unsubscribe = this.#client.onEvent((eventArg) => handlerArg({
+      type: 'state_changed', integrationDomain: this.domain, deviceId: TplinkNativeMapper.deviceId(eventArg.snapshot),
+      entityId: TplinkNativeMapper.entityId(eventArg.snapshot), timestamp: Date.parse(eventArg.snapshot.observedAt),
+      data: { entity: TplinkNativeMapper.toEntities(eventArg.snapshot)[0] },
+    }));
+    const release = (): void => {
+      unsubscribe();
+      abortSignalArg?.removeEventListener('abort', release);
+      this.#subscriptions.delete(release);
+    };
+    this.#subscriptions.add(release);
+    abortSignalArg?.addEventListener('abort', release, { once: true });
+    if (abortSignalArg?.aborted) release();
+    try { await this.#client.getSnapshot(abortSignalArg); }
+    catch (errorArg) { release(); throw errorArg; }
+    return async () => { release(); };
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const command = TplinkMapper.commandForService(await this.client.getSnapshot(), requestArg);
-    if (!command) {
-      return { success: false, error: `Unsupported TP-Link service mapping: ${requestArg.domain}.${requestArg.service}` };
+    let power: boolean;
+    try { power = TplinkNativeMapper.powerForService(this.#identity, requestArg); }
+    catch (errorArg) { return this.admissionFailure(errorArg); }
+    return this.writeResult(await this.#client.setPower(power));
+  }
+
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    let power: boolean;
+    try { power = TplinkNativeMapper.powerForFeature(this.#identity, requestArg); }
+    catch (errorArg) { return this.admissionFailure(errorArg); }
+    return this.writeResult(await this.#client.setPower(power, abortSignalArg));
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.#destroy) {
+      for (const release of [...this.#subscriptions]) release();
+      this.#destroy = this.#client.destroy().finally(() => this.#release());
     }
-    return this.client.sendCommand(command);
+    return this.#destroy;
+  }
+
+  private writeResult(dataArg: ITplinkNativeWriteResult): IServiceCallResult {
+    return {
+      success: dataArg.outcome === 'accepted', data: dataArg,
+      error: dataArg.outcome === 'accepted' ? undefined : dataArg.outcome === 'indeterminate' ?
+        'TP-Link relay execution is indeterminate; do not retry automatically.' : 'TP-Link relay write was not accepted.',
+    };
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+  private admissionFailure(errorArg: unknown): IServiceCallResult {
+    return {
+      success: false, error: errorArg instanceof Error ? errorArg.message : 'TP-Link write admission failed.',
+      data: { outcome: 'not-sent', physicalStateConfirmed: false, deviceId: this.#identity.deviceId },
+    };
   }
 }