@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/mqtt/mqtt.types.ts

@@ -18,6 +18,17 @@ export interface IMqttConfig {
   discoveryMessages?: IMqttMessage[];
   retainedMessages?: IMqttMessage[];
   entities?: IMqttEntityConfig[];
+  connectTimeoutMs?: number;
+  operationTimeoutMs?: number;
+  reconnectPeriodMs?: number;
+  maxMessageTopics?: number;
+  maxPayloadBytes?: number;
+  maxBufferedBytes?: number;
+}
+
+export interface IMqttConnectionState {
+  connected: boolean;
+  error?: Error;
 }
 
 export interface IMqttPublishOptions {
@@ -84,6 +95,8 @@ export interface IMqttEntityConfig {
   stateTopic?: string;
   commandTopic?: string;
   availabilityTopic?: string;
+  availability?: IMqttAvailability[];
+  availabilityMode?: 'all' | 'any' | 'latest';
   jsonAttributesTopic?: string;
   valueTemplate?: string;
   stateValueTemplate?: string;
@@ -101,6 +114,12 @@ export interface IMqttEntityConfig {
   rawConfig?: Record<string, unknown>;
 }
 
+export interface IMqttAvailability {
+  topic: string;
+  payloadAvailable?: string;
+  payloadNotAvailable?: string;
+}
+
 export interface IMqttManualEntry {
   host?: string;
   port?: number;

package/ts/integrations/mqtt/readme.md

@@ -0,0 +1,28 @@
+# Native MQTT runtime
+
+`MqttIntegration` connects directly to a broker over MQTT 3.1.1 TCP or TLS through MQTT.js. No Home Assistant server or access token is involved. Setup completes after broker connection and owned subscription acknowledgements. MQTT has no end marker for retained discovery replay; newly received discovery produces normalized events and later snapshots.
+
+Configuration accepts `host`, `port`, `protocol: 'mqtt' | 'mqtts'`, `username`, `password`, `clientId`, `clean`, and `keepalive`. TLS verifies certificates by default. Persistent sessions require an explicit client ID. Credentials remain in runtime configuration; this integration does not persist them.
+
+Discovery defaults to `homeassistant/#`. Both single-component and device discovery messages are supported, including abbreviations and topic bases. The latest configuration for each discovery topic replaces its predecessor; an empty payload removes it. State, availability, and attribute topics are subscribed dynamically and removed when no longer referenced. Availability lists support `all`, `any`, and `latest`. A disconnected broker marks its devices unavailable immediately.
+
+The adapter reads supported canonical platforms. Writes support default-schema power for switches, lights and fans, button press, cover open/close/stop, numeric and text values, and configured select options. JSON-schema lights, command templates, climate setpoints and other specialized control protocols are not advertised as writable. State templates support exactly `{{ value }}` and a single `value_json` property reference; unsupported templates yield an unknown value. Writes require one exact, available target with valid input; they do not modify readable state optimistically.
+
+`connectTimeoutMs` and `operationTimeoutMs` default to 7000; `reconnectPeriodMs` defaults to 1000. MQTT.js handles protocol reconnection and QoS handshakes. Connection readiness is published only after owned subscriptions are restored. QoS 0 completion confirms transport acceptance; QoS 1 and 2 completion confirms the broker protocol acknowledgement. These acknowledgements do not confirm that a physical device performed the action.
+
+Snapshots retain one latest message per topic, bounded by `maxMessageTopics` (4096), `maxPayloadBytes` (262144), and `maxBufferedBytes` (8388608). A limit violation closes the owned connection. These settings bound application snapshots, not broker retention or the protocol library's frame parser.
+
+`MqttClient` is reusable by native integrations:
+
+- `start(signal?)`, `publish(options, signal?)`, and `subscribe(filter, handler?, signal?)` are bounded operations.
+- `subscribe` callbacks receive only matching topics. Its returned asynchronous cleanup sends UNSUBSCRIBE after the final owner releases the filter.
+- `connected`, `isHealthy()`, and `onConnectionState(handler)` expose subscription readiness and connection loss.
+- `onMessage(handler)` observes messages on owned subscriptions without subscribing to the entire broker.
+- `getSnapshot(signal?)` returns current discovery and state.
+- `destroy()` closes resources and is terminal and idempotent.
+
+Abort or timeout closes the physical connection that owns the operation before rejection; an explicit subsequent `start()` can establish a fresh connection. A stale operation cannot close a later connection generation. Subscriber cleanup is independent of transport destruction.
+
+For an ecosystem that owns its own MQTT topics, set `discovery: false`, `birthMessage: false`, and `willMessage: false`, then subscribe only its selected topics. Fixture snapshots remain supported through `entities`, `discoveryMessages`, and `retainedMessages`; they do not claim a healthy broker connection.
+
+References: [MQTT.js 5.16.0](https://github.com/mqttjs/MQTT.js/tree/v5.16.0), [MQTT discovery](https://www.home-assistant.io/integrations/mqtt/), and [MQTT 3.1.1](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html).

package/ts/integrations/openhome/openhome.classes.client.ts

@@ -56,10 +56,16 @@ interface IOpenhomeLiveData {
 export class OpenhomeClient extends SimpleLocalClient<IOpenhomeConfig> {
   private cachedSnapshot?: ISimpleLocalSnapshot;
   private cachedDescription?: IOpenhomeDeviceDescription;
-  private readonly soapClient = new plugins.ecobridgeDeviceManager.UpnpSoapClient('');
+  private readonly soapClient?: plugins.ecobridgeDeviceManager.UpnpSoapClient;
 
   constructor(private readonly configArg: IOpenhomeConfig) {
     super(openhomeProfile, configArg);
+    const location = this.descriptionUrl();
+    if (location && !configArg.client && !configArg.snapshotProvider) {
+      this.soapClient = new plugins.ecobridgeDeviceManager.UpnpSoapClient(location, {
+        timeoutMs: configArg.timeoutMs ?? 5000,
+      });
+    }
   }
 
   public override async getSnapshot(forceRefreshArg = false): Promise<ISimpleLocalSnapshot> {
@@ -114,6 +120,8 @@ export class OpenhomeClient extends SimpleLocalClient<IOpenhomeConfig> {
   }
 
   public override async destroy(): Promise<void> {
+    this.cachedSnapshot = undefined;
+    await this.soapClient?.close();
     await this.configArg.client?.destroy?.();
   }
 
@@ -312,20 +320,9 @@ export class OpenhomeClient extends SimpleLocalClient<IOpenhomeConfig> {
     if (!location) {
       throw new Error('OpenHome live HTTP/SOAP support requires config.url, config.host containing the SSDP location URL, or config.host plus config.path.');
     }
-    const timeoutMs = this.configArg.timeoutMs || 5000;
-    const abortController = new AbortController();
-    const timer = setTimeout(() => abortController.abort(), timeoutMs);
-    try {
-      const response = await globalThis.fetch(location, { headers: { accept: 'application/xml, text/xml;q=0.9, */*;q=0.8' }, signal: abortController.signal });
-      const xml = await response.text();
-      if (!response.ok) {
-        throw new Error(`OpenHome device description ${location} failed with HTTP ${response.status}: ${xml.slice(0, 160)}`);
-      }
-      this.cachedDescription = parseDeviceDescription(location, xml);
-      return this.cachedDescription;
-    } finally {
-      clearTimeout(timer);
-    }
+    const xml = await this.requireSoapClient().getXml(location);
+    this.cachedDescription = parseDeviceDescription(location, xml);
+    return this.cachedDescription;
   }
 
   private async productInfo(descriptionArg: IOpenhomeDeviceDescription): Promise<Record<string, unknown>> {
@@ -453,9 +450,9 @@ export class OpenhomeClient extends SimpleLocalClient<IOpenhomeConfig> {
     }
   }
 
-  private async soapValues(descriptionArg: IOpenhomeDeviceDescription, serviceNameArg: string, actionArg: string, tagsArg: string[], argsArg: Record<string, string | number> = {}): Promise<Record<string, string>> {
+  private async soapValues(descriptionArg: IOpenhomeDeviceDescription, serviceNameArg: string, actionArg: string, tagsArg: string[], argsArg: Record<string, string | number> = {}): Promise<Record<string, string | undefined>> {
     const response = await this.soap(descriptionArg, serviceNameArg, actionArg, argsArg);
-    return Object.fromEntries(tagsArg.map((tagArg) => [tagArg, unescapeXml(this.soapClient.extractValue(response, tagArg))]));
+    return this.requireSoapClient().extractOptionalValues(response, tagsArg);
   }
 
   private async soap(descriptionArg: IOpenhomeDeviceDescription, serviceNameArg: string, actionArg: string, argsArg: Record<string, string | number> = {}): Promise<string> {
@@ -463,7 +460,14 @@ export class OpenhomeClient extends SimpleLocalClient<IOpenhomeConfig> {
     if (!service) {
       throw new Error(`OpenHome service ${serviceNameArg} is not available on ${descriptionArg.location}.`);
     }
-    return await this.soapClient.soapAction(service.controlUrl, service.serviceType, actionArg, argsArg);
+    return await this.requireSoapClient().soapAction(service.controlUrl, service.serviceType, actionArg, argsArg);
+  }
+
+  private requireSoapClient(): plugins.ecobridgeDeviceManager.UpnpSoapClient {
+    if (!this.soapClient) {
+      throw new Error('OpenHome SOAP requires a configured device description URL.');
+    }
+    return this.soapClient;
   }
 
   private service(descriptionArg: IOpenhomeDeviceDescription, serviceNameArg: string): IOpenhomeServiceDescription | undefined {

package/ts/integrations/roku/readme.md

@@ -0,0 +1,95 @@
+# Roku
+
+Native local Roku ECP queries and controls for `@smarthome.exchange/integrations`. Setup binds one configured endpoint to its reported device UDN. The runtime reads device information, installed apps and the active app from the device.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Setup
+
+Install the parent package using pnpm. Import `RokuIntegration` from its public exports:
+
+```bash
+pnpm add @smarthome.exchange/integrations
+```
+
+```typescript
+import { RokuIntegration } from '@smarthome.exchange/integrations';
+
+const integration = new RokuIntegration();
+const runtime = await integration.setup({
+  host: '192.168.1.60',
+  port: 8060,
+  udn: '015e5108-9000-1046-8035-b0a737964dfb',
+  requestTimeoutMs: 5000,
+}, {});
+
+try {
+  const [device] = await runtime.devices();
+  await runtime.callService?.({
+    domain: 'remote',
+    service: 'send_command',
+    target: { deviceId: device.id },
+    data: { command: 'Home' },
+  });
+} finally {
+  await integration.destroy();
+}
+```
+
+Read `udn` from the device's `GET /query/device-info` response. It is a UUID, distinct from the serial number in Roku's SSDP USN. Configuration requires a literal private or loopback IPv4 address, an integer TCP port, this exact UDN and an optional operation deadline of 1–60000 ms. The default port is 8060 and deadline is 5000 ms. Hostnames, URL credentials, fixture snapshots and additional configuration fields are rejected. Provision configuration through the hub's scoped configuration store; this domain does not persist application data.
+
+Every query reports fresh device state. Device and entity IDs derive from UDN, so renaming the device leaves its identity stable. `power_mode` is a read-only field containing the reported value, or `null` when absent. The active-app feature contains the reported app ID; the entity state contains the reported app name. Neither claims playback activity or an inferred power state.
+
+## Controls
+
+Services require the exact connected `deviceId` or `entityId`. Supplying both requires both to match. Empty targets, foreign targets, extra arguments and accessor properties are rejected before effects.
+
+| Service | Data | Behavior |
+| --- | --- | --- |
+| `remote.send_command` | `{ command: 'Home' }` | One supported ECP keypress. |
+| `media_player.select_source` | `{ source: '837' }` | Launch one currently installed app by its exact ID. |
+
+Feature writes support `remote_key` with a supported key name, or `active_app` with an installed app ID. The runtime checks the caller's device domain and UDN target and uses its canonical writable feature list. It does not trust caller-provided writable flags.
+
+Migrate calls to `media_player.play_pause` to an explicit `remote.send_command` request with `data: { command: 'Play' }` and the same exact device or entity target. The integration reports no authoritative playback state or app-specific playback capability, so it rejects `play_pause` without dispatching a key. Explicit remote `Play` remains available and confirms only that ECP accepted the keypress.
+
+Key names are case-sensitive: `Home`, `Rev`, `Fwd`, `Play`, `Select`, `Left`, `Right`, `Down`, `Up`, `Back`, `InstantReplay`, `Info`, `Backspace`, `Search`, `Enter`, `VolumeUp`, `VolumeDown`, and `VolumeMute`. Volume keys require `is-tv` or `supports-audio-volume-control` in the current device response. `VolumeMute` is a toggle, not a request to set a Boolean mute state. The endpoint identity is rechecked before every control; app launches also refresh the installed-app catalogue. Screensavers cannot be launched through this runtime.
+
+Success confirms an ECP HTTP acceptance with `data.confirmation: 'ecp-http'` and `data.effectOutcome: 'accepted'`. It does not confirm a physical outcome. Controls issue one POST, never retry, and never update state optimistically. A `RokuRequestError` distinguishes `not-sent`, `rejected` and `indeterminate`; callers must not replay an indeterminate effect automatically.
+
+Power controls, absolute volume, semantic play/pause or play-pause services, next/previous track, held keys, command arrays, text entry, app installation, arbitrary deep-link parameters and undocumented media-URL playback are not exposed.
+
+## Discovery and lifecycle
+
+Discovery admits passive `roku:ecp` SSDP records with a canonical Roku USN and a credential-free local HTTP origin on port 8060, or manual entries explicitly marked `integrationDomain: 'roku'`. It copies only allowlisted candidate fields and never follows LOCATION or retains arbitrary metadata. The config flow still requires the verified device-info UDN. Active SSDP probing belongs to the shared device manager and is pending its published LOCATION/lifecycle correction.
+
+The client limits each operation to its configured deadline, at most eight active operations and 256 KiB per response. XML is validated with a bounded parser; DTDs, duplicate required fields and malformed catalogues fail closed. Redirects are rejected. `devices(signal)` and `writeFeature(request, signal)` support cancellation. A setup-context signal owns the connection lifetime. Destroy aborts and joins active operations, closes every runtime owned by the integration and permanently refuses new setup or controls.
+
+ECP uses unauthenticated local HTTP. UDN matching detects endpoint changes but is not cryptographic device authentication. The hub remains responsible for home access, scoped authorization, approvals and audit receipts. Fixture verification uses local HTTP servers only; physical-device and firmware behavior has not been tested.
+
+## Protocol references
+
+[Roku's current ECP documentation](https://developer.roku.com/dev/docs/external-control-api) specifies device-info, keypress, app launch and SSDP. It documents the device setting required for keypress on Roku OS 14.1 and later. Its current command table omits `query/apps` and `query/active-app`; their maintained response contract was checked against [Home Assistant's Roku ECP client source](https://github.com/ctalkington/python-rokuecp/blob/main/src/rokuecp/rokuecp.py). Hardware compatibility for these omitted queries remains unconfirmed.
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/integrations/roku/roku.classes.client.ts

@@ -1,165 +1,228 @@
-import type { IRokuApp, IRokuConfig, IRokuDeviceInfo, IRokuSnapshot, TRokuKeypress } from './roku.types.js';
+import * as plugins from '../../plugins.js';
+import type { IRokuActiveApp, IRokuApp, IRokuClientOptions, IRokuConfig, IRokuDeviceInfo, IRokuSnapshot, TRokuEffectOutcome } from './roku.types.js';
+import { normalizeRokuUdn, readRokuRecord, validateRokuAppId, validateRokuConfig, validateRokuKey } from './roku.validation.js';
+
+interface IRokuOperation {
+  signal: AbortSignal;
+  effectSent: boolean;
+}
+
+const isRecord = (inputArg: unknown): inputArg is Record<string, unknown> => typeof inputArg === 'object' && inputArg !== null && !Array.isArray(inputArg);
+const maxResponseBytes = 256 * 1024;
+
+export class RokuRequestError extends Error {
+  constructor(messageArg: string, public readonly effectOutcome: TRokuEffectOutcome) {
+    super(messageArg);
+    this.name = 'RokuRequestError';
+  }
+}
 
 export class RokuClient {
-  constructor(private readonly config: IRokuConfig) {}
+  private readonly config: IRokuConfig;
+  private readonly baseUrl: string;
+  private readonly lifetime = new AbortController();
+  private readonly ownerSignal?: AbortSignal;
+  private readonly operations = new Set<Promise<unknown>>();
+  private closePromise?: Promise<void>;
+  private readonly parser = new plugins.fastXmlParser.XMLParser({
+    ignoreAttributes: false, ignoreDeclaration: true, ignorePiTags: true,
+    parseTagValue: false, parseAttributeValue: false, trimValues: true, maxNestedTags: 8,
+    isArray: (tagArg, pathArg) => tagArg === 'app' && pathArg === 'apps.app',
+  });
+  private readonly onOwnerAbort = (): void => { void this.destroy(); };
+
+  constructor(configArg: IRokuConfig, optionsArg: IRokuClientOptions = {}) {
+    this.config = validateRokuConfig(configArg);
+    this.baseUrl = `http://${this.config.host}:${this.config.port}`;
+    const signal = readRokuRecord(optionsArg, ['abortSignal']).abortSignal;
+    if (signal !== undefined && !(signal instanceof AbortSignal)) throw new Error('Roku owner signal must be an AbortSignal.');
+    this.ownerSignal = signal;
+    this.ownerSignal?.addEventListener('abort', this.onOwnerAbort, { once: true });
+    if (this.ownerSignal?.aborted) this.onOwnerAbort();
+  }
 
-  public async getSnapshot(): Promise<IRokuSnapshot> {
-    const [deviceInfo, apps, activeApp] = await Promise.all([
-      this.getDeviceInfo(),
-      this.getApps(),
-      this.getActiveApp(),
-    ]);
-    return { deviceInfo, apps, activeApp };
+  public get isClosed(): boolean { return this.lifetime.signal.aborted; }
+
+  public getSnapshot(abortSignalArg?: AbortSignal): Promise<IRokuSnapshot> {
+    return this.runOperation(async (operationArg) => {
+      const deviceInfo = await this.readDeviceInfo(operationArg);
+      const apps = await this.readApps(operationArg);
+      const activeApp = await this.readActiveApp(operationArg);
+      return { deviceInfo, apps, activeApp, observedAt: new Date().toISOString() };
+    }, abortSignalArg);
   }
 
-  public async getDeviceInfo(): Promise<IRokuDeviceInfo> {
-    if (this.config.deviceInfo) {
-      return this.config.deviceInfo;
-    }
-    const xml = await this.requestText('/query/device-info');
-    return {
-      serialNumber: this.readXmlTag(xml, 'serial-number'),
-      deviceId: this.readXmlTag(xml, 'device-id'),
-      vendorName: this.readXmlTag(xml, 'vendor-name'),
-      modelName: this.readXmlTag(xml, 'model-name'),
-      modelNumber: this.readXmlTag(xml, 'model-number'),
-      friendlyDeviceName: this.readXmlTag(xml, 'friendly-device-name'),
-      userDeviceName: this.readXmlTag(xml, 'user-device-name'),
-      deviceType: this.readXmlTag(xml, 'device-type'),
-      softwareVersion: this.readXmlTag(xml, 'software-version'),
-      powerMode: this.readXmlTag(xml, 'power-mode'),
-      supportsSuspend: this.readXmlTag(xml, 'supports-suspend') === 'true',
-    };
+  public getDeviceInfo(abortSignalArg?: AbortSignal): Promise<IRokuDeviceInfo> {
+    return this.runOperation((operationArg) => this.readDeviceInfo(operationArg), abortSignalArg);
   }
 
-  public async getApps(): Promise<IRokuApp[]> {
-    if (this.config.apps) {
-      return this.config.apps;
-    }
-    const xml = await this.requestText('/query/apps');
-    return this.readApps(xml);
+  public getApps(abortSignalArg?: AbortSignal): Promise<IRokuApp[]> {
+    return this.runOperation(async (operationArg) => {
+      await this.readDeviceInfo(operationArg);
+      return this.readApps(operationArg);
+    }, abortSignalArg);
   }
 
-  public async getActiveApp(): Promise<IRokuApp | undefined> {
-    if (this.config.activeApp) {
-      return this.config.activeApp;
-    }
-    const xml = await this.requestText('/query/active-app');
-    return this.readApps(xml)[0];
+  public getActiveApp(abortSignalArg?: AbortSignal): Promise<IRokuActiveApp> {
+    return this.runOperation(async (operationArg) => {
+      await this.readDeviceInfo(operationArg);
+      return this.readActiveApp(operationArg);
+    }, abortSignalArg);
   }
 
-  public async keypress(keyArg: TRokuKeypress | string): Promise<void> {
-    await this.requestText(`/keypress/${encodeURIComponent(this.toEcpKey(keyArg))}`, 'POST');
+  public keypress(keyArg: string, abortSignalArg?: AbortSignal): Promise<void> {
+    const key = validateRokuKey(keyArg);
+    return this.runOperation(async (operationArg) => {
+      validateRokuKey(key, await this.readDeviceInfo(operationArg));
+      await this.requestText(`/keypress/${key}`, 'POST', operationArg);
+    }, abortSignalArg);
   }
 
-  public async launch(appIdArg: string, paramsArg: Record<string, string | number | boolean> = {}): Promise<void> {
-    const searchParams = new URLSearchParams();
-    for (const [key, value] of Object.entries(paramsArg)) {
-      searchParams.set(key, String(value));
-    }
-    const suffix = searchParams.size ? `?${searchParams.toString()}` : '';
-    await this.requestText(`/launch/${encodeURIComponent(appIdArg)}${suffix}`, 'POST');
+  public launch(appIdArg: string, abortSignalArg?: AbortSignal): Promise<void> {
+    const appId = validateRokuAppId(appIdArg);
+    return this.runOperation(async (operationArg) => {
+      await this.readDeviceInfo(operationArg);
+      const app = (await this.readApps(operationArg)).find((appArg) => appArg.id === appId && appArg.type !== 'ssvr');
+      if (!app) throw new Error('Roku app id is not in the current installed-app catalogue.');
+      await this.requestText(`/launch/${encodeURIComponent(app.id)}`, 'POST', operationArg);
+    }, abortSignalArg);
   }
 
-  public async playUrl(urlArg: string, mediaTypeArg: 'video' | 'audio' = 'video', titleArg?: string): Promise<void> {
-    const params: Record<string, string> = {
-      u: urlArg,
-      t: mediaTypeArg === 'audio' ? 'a' : 'v',
-    };
-    if (titleArg) {
-      params[mediaTypeArg === 'audio' ? 'songName' : 'videoName'] = titleArg;
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.lifetime.abort(new DOMException('Roku client is closed.', 'AbortError'));
+      this.ownerSignal?.removeEventListener('abort', this.onOwnerAbort);
+      this.closePromise = Promise.allSettled([...this.operations]).then(() => undefined);
     }
-    await this.launch(this.config.playMediaAppId || '15985', params);
+    return this.closePromise;
   }
 
-  public async destroy(): Promise<void> {}
+  private runOperation<TValue>(operationArg: (contextArg: IRokuOperation) => Promise<TValue>, abortSignalArg?: AbortSignal): Promise<TValue> {
+    if (this.isClosed) return Promise.reject(new RokuRequestError('Roku client is closed.', 'not-sent'));
+    if (abortSignalArg?.aborted) return Promise.reject(new RokuRequestError('Roku operation was cancelled.', 'not-sent'));
+    if (this.operations.size >= 8) return Promise.reject(new RokuRequestError('Roku has reached its active-operation limit.', 'not-sent'));
+    const controller = new AbortController();
+    const onAbort = (): void => controller.abort(new DOMException('Roku operation was cancelled.', 'AbortError'));
+    this.lifetime.signal.addEventListener('abort', onAbort, { once: true });
+    abortSignalArg?.addEventListener('abort', onAbort, { once: true });
+    const timeout = setTimeout(() => controller.abort(new DOMException('Roku operation exceeded its deadline.', 'TimeoutError')), this.config.requestTimeoutMs);
+    const context: IRokuOperation = { signal: controller.signal, effectSent: false };
+    const result = Promise.resolve().then(() => operationArg(context)).catch((errorArg: unknown) => {
+      if (errorArg instanceof RokuRequestError) throw errorArg;
+      const reason: unknown = controller.signal.aborted ? controller.signal.reason : errorArg;
+      const message = reason instanceof Error ? reason.message : 'Roku operation failed.';
+      throw new RokuRequestError(message, context.effectSent ? 'indeterminate' : 'not-sent');
+    }).finally(() => {
+      clearTimeout(timeout);
+      this.lifetime.signal.removeEventListener('abort', onAbort);
+      abortSignalArg?.removeEventListener('abort', onAbort);
+      this.operations.delete(result);
+    });
+    this.operations.add(result);
+    return result;
+  }
 
-  private async requestText(pathArg: string, methodArg: 'GET' | 'POST' = 'GET'): Promise<string> {
-    if (!this.config.host) {
-      throw new Error('Roku host is required when fixture data is not provided.');
-    }
-    const response = await globalThis.fetch(`${this.baseUrl()}${pathArg}`, { method: methodArg });
-    const text = await response.text();
+  private async requestText(pathArg: string, methodArg: 'GET' | 'POST', operationArg: IRokuOperation): Promise<string> {
+    operationArg.signal.throwIfAborted();
+    if (methodArg === 'POST') operationArg.effectSent = true;
+    const response = await globalThis.fetch(`${this.baseUrl}${pathArg}`, {
+      method: methodArg, redirect: 'error', signal: operationArg.signal,
+      headers: { accept: 'application/xml, text/xml' },
+    });
     if (!response.ok) {
-      throw new Error(`Roku request ${pathArg} failed with HTTP ${response.status}: ${text}`);
+      await response.body?.cancel();
+      throw new RokuRequestError(`Roku ECP returned HTTP ${response.status}.`, methodArg === 'POST' && response.status >= 400 && response.status < 500 ? 'rejected' : operationArg.effectSent ? 'indeterminate' : 'not-sent');
+    }
+    const reader = response.body?.getReader();
+    if (!reader) return '';
+    const chunks: Uint8Array[] = [];
+    let bytes = 0;
+    let completed = false;
+    try {
+      while (true) {
+        const next = await reader.read();
+        if (next.done) { completed = true; break; }
+        bytes += next.value.byteLength;
+        if (bytes > maxResponseBytes) throw new Error('Roku ECP response exceeds 256 KiB.');
+        chunks.push(next.value);
+      }
+      const decoder = new TextDecoder('utf-8', { fatal: true });
+      return chunks.map((chunkArg) => decoder.decode(chunkArg, { stream: true })).join('') + decoder.decode();
+    } finally {
+      if (!completed) await reader.cancel().catch(() => undefined);
+      reader.releaseLock();
     }
-    return text;
   }
 
-  private readApps(xmlArg: string): IRokuApp[] {
-    const apps: IRokuApp[] = [];
-    const regex = /<app\s+([^>]*)>([\s\S]*?)<\/app>/g;
-    let match: RegExpExecArray | null;
-    while ((match = regex.exec(xmlArg))) {
-      const attrs = this.readAttributes(match[1]);
-      const id = attrs.id;
-      if (!id) {
-        continue;
-      }
-      apps.push({
-        id,
-        name: this.unescapeXml(match[2].trim()),
-        type: attrs.type,
-        version: attrs.version,
-      });
+  private parseRoot(xmlArg: string, rootNameArg: string): unknown {
+    if (/<!\s*(?:DOCTYPE|ENTITY)/i.test(xmlArg) || plugins.fastXmlParser.XMLValidator.validate(xmlArg) !== true) {
+      throw new Error('Roku ECP returned malformed XML.');
     }
-    return apps;
+    const parsed: unknown = this.parser.parse(xmlArg);
+    if (!isRecord(parsed) || Object.keys(parsed).length !== 1 || !(rootNameArg in parsed)) {
+      throw new Error(`Roku ECP response must have one ${rootNameArg} root.`);
+    }
+    return parsed[rootNameArg];
   }
 
-  private readAttributes(valueArg: string): Record<string, string> {
-    const attrs: Record<string, string> = {};
-    const regex = /([a-zA-Z0-9_-]+)="([^"]*)"/g;
-    let match: RegExpExecArray | null;
-    while ((match = regex.exec(valueArg))) {
-      attrs[match[1]] = this.unescapeXml(match[2]);
+  private textField(recordArg: Record<string, unknown>, fieldArg: string): string | undefined {
+    const value = recordArg[fieldArg];
+    if (value === undefined) return undefined;
+    if (typeof value !== 'string' || value.length > 1024 || /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(value)) {
+      throw new Error('Roku ECP returned an invalid text field.');
     }
-    return attrs;
-  }
-
-  private readXmlTag(xmlArg: string, tagArg: string): string | undefined {
-    const escapedTag = tagArg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const regex = new RegExp(`<${escapedTag}>([\\s\\S]*?)<\\/${escapedTag}>`, 'i');
-    const match = regex.exec(xmlArg);
-    return match?.[1] ? this.unescapeXml(match[1].trim()) : undefined;
-  }
-
-  private toEcpKey(keyArg: string): string {
-    const normalized = keyArg.replace(/[_\s-]+/g, '').toLowerCase();
-    const keys: Record<string, TRokuKeypress> = {
-      home: 'Home',
-      rev: 'Rev',
-      reverse: 'Rev',
-      fwd: 'Fwd',
-      forward: 'Fwd',
-      play: 'Play',
-      pause: 'Play',
-      select: 'Select',
-      left: 'Left',
-      right: 'Right',
-      down: 'Down',
-      up: 'Up',
-      back: 'Back',
-      instantreplay: 'InstantReplay',
-      info: 'Info',
-      backspace: 'Backspace',
-      search: 'Search',
-      enter: 'Enter',
-      poweron: 'PowerOn',
-      poweroff: 'PowerOff',
-      power: 'Power',
-      volumeup: 'VolumeUp',
-      volumedown: 'VolumeDown',
-      volumemute: 'VolumeMute',
-      mute: 'VolumeMute',
+    return value;
+  }
+
+  private booleanField(recordArg: Record<string, unknown>, fieldArg: string): boolean | undefined {
+    const value = this.textField(recordArg, fieldArg);
+    if (value === undefined) return undefined;
+    if (value !== 'true' && value !== 'false') throw new Error('Roku ECP returned an invalid boolean field.');
+    return value === 'true';
+  }
+
+  private async readDeviceInfo(operationArg: IRokuOperation): Promise<IRokuDeviceInfo> {
+    const record = this.parseRoot(await this.requestText('/query/device-info', 'GET', operationArg), 'device-info');
+    if (!isRecord(record)) throw new Error('Roku device-info is not an object.');
+    const udn = normalizeRokuUdn(this.textField(record, 'udn'));
+    if (udn !== this.config.udn) throw new Error('Roku endpoint no longer reports the configured UDN.');
+    const vendorName = this.textField(record, 'vendor-name');
+    if (vendorName !== undefined && vendorName !== 'Roku') throw new Error('Roku endpoint reports a different vendor.');
+    return {
+      udn, vendorName, serialNumber: this.textField(record, 'serial-number'), deviceId: this.textField(record, 'device-id'),
+      modelName: this.textField(record, 'model-name'), modelNumber: this.textField(record, 'model-number'),
+      friendlyDeviceName: this.textField(record, 'friendly-device-name'), userDeviceName: this.textField(record, 'user-device-name'),
+      softwareVersion: this.textField(record, 'software-version'), powerMode: this.textField(record, 'power-mode'),
+      isTv: this.booleanField(record, 'is-tv'), supportsAudioVolumeControl: this.booleanField(record, 'supports-audio-volume-control'),
     };
-    return keys[normalized] || keyArg;
   }
 
-  private baseUrl(): string {
-    return `http://${this.config.host}:${this.config.port || 8060}`;
+  private parseApp(inputArg: unknown, requireIdArg: boolean): IRokuActiveApp {
+    if (typeof inputArg === 'string' && !requireIdArg && inputArg.length > 0 && inputArg.length <= 1024) return { name: inputArg };
+    if (!isRecord(inputArg)) throw new Error('Roku ECP returned an invalid app entry.');
+    const name = this.textField(inputArg, '#text');
+    if (!name) throw new Error('Roku app entry has no name.');
+    const id = this.textField(inputArg, '@_id');
+    if (requireIdArg || id !== undefined) validateRokuAppId(id);
+    return { id, name, type: this.textField(inputArg, '@_type'), version: this.textField(inputArg, '@_version') ?? this.textField(inputArg, '@_Version') };
+  }
+
+  private async readApps(operationArg: IRokuOperation): Promise<IRokuApp[]> {
+    const root = this.parseRoot(await this.requestText('/query/apps', 'GET', operationArg), 'apps');
+    if (root === '') return [];
+    if (!isRecord(root) || !Array.isArray(root.app) || root.app.length > 2048) throw new Error('Roku apps catalogue is malformed.');
+    const apps: IRokuApp[] = [];
+    for (const entry of root.app) {
+      const app = this.parseApp(entry, true);
+      if (!app.id || apps.some((existingArg) => existingArg.id === app.id)) throw new Error('Roku apps catalogue has duplicate or missing ids.');
+      apps.push({ id: app.id, name: app.name, type: app.type, version: app.version });
+    }
+    return apps;
   }
 
-  private unescapeXml(valueArg: string): string {
-    return valueArg.replace(/&apos;/g, "'").replace(/&quot;/g, '"').replace(/&gt;/g, '>').replace(/&lt;/g, '<').replace(/&amp;/g, '&');
+  private async readActiveApp(operationArg: IRokuOperation): Promise<IRokuActiveApp> {
+    const root = this.parseRoot(await this.requestText('/query/active-app', 'GET', operationArg), 'active-app');
+    if (!isRecord(root)) throw new Error('Roku active-app response is malformed.');
+    return this.parseApp(root.app, false);
   }
 }