@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/daikin/readme.md

@@ -0,0 +1,83 @@
+# Daikin selected BRP069 integration
+
+This integration connects one explicitly selected Daikin BRP069 LAN controller to native smarthome.exchange devices, entities, service calls, feature writes and observation events. The published `@ecobridge.xyz/devicemanager` `DaikinProtocol` owns HTTP, validation, fresh write preflight, preservation, bounded FIFO operations, cancellation and terminal transport drain.
+
+## 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.
+
+## Connect and control
+
+```typescript
+import { DaikinIntegration, type IDaikinNativeConfig } from '@smarthome.exchange/integrations';
+
+const integration = new DaikinIntegration();
+const config: IDaikinNativeConfig = {
+  homeId: 'selected-home',
+  apiVariant: 'brp069',
+  host: '192.168.1.40',
+  expectedMac: '409F38D107AC',
+  allowPlaintext: true,
+  timeoutMs: 5000,
+};
+const runtime = await integration.setup(config, { homeId: 'selected-home' });
+try {
+  const device = (await runtime.devices())[0];
+  const power = device.features.find((feature) => feature.id === 'power');
+  if (power?.writable) {
+    const result = await runtime.writeFeature!({ device, feature: power, value: false });
+    console.log(result.success, result.data);
+  }
+} finally {
+  await integration.destroy();
+}
+```
+
+Live setup requires an exact home ID, explicit `brp069` selection, private literal IPv4 address, exact twelve-hex-digit unicast adapter MAC, and `allowPlaintext: true`. Loopback is accepted for local fixtures. The LAN API is unauthenticated HTTP; observing the expected MAC does not authenticate the peer. DNS, automatic family selection, redirects, credentials, cloud fallback and effect retries are unsupported. `name`, `port`, `timeoutMs`, `maxResponseBytes` and `maxPendingOperations` are optional. Protocol limits are enforced by the published protocol.
+
+The embedding host must separately pass its selected `homeId` in setup and configuration-flow context. Configuration, editable form values, discovery and store scope cannot select the owner home. An optional constructor binding, `new DaikinIntegration({ homeId: 'selected-home' })`, adds a consistency constraint and still requires explicit context home. An unbound instance binds once on its first valid host admission and keeps that home after failed verification. Flow and setup share admission. The public `DaikinClient(config, { homeId: 'selected-home' })` also requires independent host context and captures it before protocol construction. This is a trusted embedding-host contract; a home string is not an authentication credential.
+
+Configuration flow and setup independently read basic information, model information and current control. A prior successful flow does not authorize setup against a changed endpoint. Discovery matches only bounded received mDNS, UDP, HTTP and manual hints; it sends no broadcasts or probes and copies no arbitrary metadata, credentials or payloads into candidates. A discovery match requires independent selected-controller verification.
+
+## Native observations and effects
+
+Device and entity IDs contain the exact home scope and adapter identity. Power and an observed target temperature are mapped from actual protocol state. Mode, target humidity, fan and direction remain observations. This protocol does not read ambient temperature, ambient humidity, energy, zones or physical HVAC action; it does not create those sensors or infer cooling/heating activity from the configured operating mode.
+
+Only explicit boolean power and explicit integer Celsius targets are writable. Targets require the current observed cool mode (18–33 °C) or heat mode (10–31 °C), supported temperature advertisement, the recorded standard `temp_rng=0` model family and a numeric current target. Other range encodings remain read only. An incomplete required fan/direction control family also remains read only. Capabilities shown by a previous read are descriptive; each effect delegates fresh capability checks to the protocol. Target writes preserve power and never implicitly turn on the controller. Every write preserves current required mode, target, humidity, fan and direction fields except the explicitly requested power or target.
+
+Services accept an exact owned entity or device target. Supplying both requires agreement. Platform domains must match the selected climate or power entity. Supported controls are `climate.turn_on`, `climate.turn_off`, `climate.set_temperature` with only numeric `temperature`, and `switch.turn_on`/`turn_off` on the power entity. `daikin.refresh` returns a fresh snapshot for an owned target. Mode changes, fan changes, direction changes, humidity changes, presets, toggles, zones and implicit values are rejected. Feature writes require an exact owned device and supported feature shape. Accessors, symbol fields, unknown service fields and unrelated targets are rejected before effect traffic.
+
+Results forward the protocol acknowledgment, requested values, independent observation and `effectOutcome`. `success: true` requires `confirmed`; accepted mismatched readback remains `indeterminate`. Errors retain `not-sent`, `rejected` or `indeterminate`. There are no optimistic snapshot mutations or automatic effect replays. Confirmation describes state at observation; another controller can change the unit between preflight and dispatch because BRP069 has no compare-and-set operation.
+
+`runtime.subscribe` emits changed state after requested fresh reads or effect readback, availability changes and errors. It does not start polling or claim a device push stream. Unsubscribe and subscriber abort remove that listener. A failed listener is removed and reported without changing a completed effect outcome. Setup lifetime abort, runtime destruction and integration destruction cancel owned HTTP work, remove listeners, drain queued and active protocol operations, and permanently reject further work. Integration destruction also joins pending setup and configuration-flow verification continuations and prevents later submission of previously returned forms. Configuration-flow and integration destruction wait for every owned cleanup to settle even when another cleanup fails. They then reject with an `AggregateError` preserving original failures inside resource groups. Repeated destruction returns the same terminal promise. Failed resources remain owned and count toward capacity; `integration.retryCleanup()` or `configFlow.retryCleanup()` explicitly retries cleanup without replaying transport operations. The shared default capacity is 16 resources across pending setup, runtimes and flow verification; `new DaikinIntegration({ capacity: 8 })` can choose a smaller bound. Closing the child flow leaves successful integration runtimes active. Caller-owned stores and databases remain untouched.
+
+## Configuration ownership and migration
+
+`configFlow.start(candidate, { homeId: 'selected-home' })` captures the host context and returns verified, credential-free configuration for that home. The form has no editable home field and rejects a conflicting submitted home before HTTP. It performs no persistence writes. Setup, flow and public-client context accept an optional caller-owned encrypted `NoSqlConfigStore` whose home ID and `daikin` domain must exactly match the admitted host home. Structural stores cannot grant admission. `IntegrationRuntimeManager` owns runtime activation and retirement. The caller decides whether and under which key to store returned configuration; the integration never closes the caller's store, database or encryption provider. No configuration persistence is required for credential-free BRP069 control.
+
+Native setup now requires `IDaikinNativeConfig`; configurations containing injected clients, command executors, snapshots, raw data, API keys or passwords are rejected. Automatic and unsupported controller families are rejected explicitly rather than becoming a ready fixture runtime. `DaikinClient.execute`, legacy command executor/client interfaces and `DaikinMapper.commandForService` are replaced by public-protocol-backed `setControl`, exact-target runtime services and `writeFeature`.
+
+The existing `DaikinMapper.toSnapshot`, raw-response parsers and translation helpers remain explicit offline utilities for BRP069, BRP072C, AirBase, SkyFi and BRP084 data. Their devices expose no writable features and their entities advertise no service controls. They do not create a live runtime. Operating mode alone is no longer reported as physical heating/cooling activity.
+
+Real HTTP and in-memory NoSQL fixtures cover these contracts. Physical Daikin hardware and firmware interoperability have not been verified. The protocol's primary sources and detailed wire limits are documented in the published [devicemanager README](https://code.foss.global/ecobridge.xyz/devicemanager#readme).
+
+## 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](../../../license.md).
+
+**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/deconz/deconz.classes.client.ts

@@ -1,238 +1,291 @@
-import type {
-  IDeconzConfig,
-  IDeconzGatewayConfig,
-  IDeconzGroupActionPatch,
-  IDeconzLightStatePatch,
-  IDeconzSensorConfigPatch,
-  IDeconzSensorStatePatch,
-  IDeconzSnapshot,
-  IDeconzWebsocketEvent,
-} from './deconz.types.js';
-
-type TWebSocketMessage = { data: unknown };
-
-type TWebSocketLike = {
-  close(): void;
-  addEventListener?: (eventArg: 'message', handlerArg: (messageArg: TWebSocketMessage) => void) => void;
-  onmessage?: (messageArg: TWebSocketMessage) => void;
-};
-
-type TWebSocketConstructor = new (urlArg: string) => TWebSocketLike;
+import type { IDeconzConfig, IDeconzGatewayConfig, IDeconzGroupActionPatch, IDeconzLightStatePatch, IDeconzSensorConfigPatch, IDeconzSensorStatePatch, IDeconzSnapshot, IDeconzWebsocketEvent } from './deconz.types.js';
+import { deconzEndpoint, deconzGatewayConfig, deconzGroupActionPatch, deconzLightStatePatch, deconzPort, deconzSensorConfigPatch, deconzSensorStatePatch, deconzSnapshot, deconzWebsocketEvent, isDeconzRecord } from './deconz.validation.js';
 
-export class DeconzClient {
-  constructor(private readonly config: IDeconzConfig) {}
+export class DeconzRequestError extends Error {
+  constructor(messageArg: string, public readonly apiErrorType?: number) { super(messageArg); }
+}
 
-  public async getSnapshot(): Promise<IDeconzSnapshot> {
-    if (this.config.snapshot) {
-      return this.config.snapshot;
+export class DeconzClient {
+  private readonly config: IDeconzConfig;
+  private readonly endpoint?: URL;
+  private readonly timeoutMs: number;
+  private readonly lifetime = new AbortController();
+  private readonly operations = new Set<Promise<unknown>>();
+  private readonly subscriptions = new Set<() => Promise<void>>();
+  private streamHealthy = true;
+  private gatewayHealthy = false;
+  private gatewayId?: string;
+
+  constructor(configArg: IDeconzConfig, private readonly abortSignal?: AbortSignal) {
+    this.config = structuredClone(configArg);
+    const config = this.config;
+    if (config.snapshot && config.host !== undefined) throw new Error('deCONZ snapshot fixtures cannot be combined with a live endpoint.');
+    this.timeoutMs = config.requestTimeoutMs ?? 15000;
+    if (!Number.isInteger(this.timeoutMs) || this.timeoutMs < 1 || this.timeoutMs > 2147483647) {
+      throw new Error('deCONZ requestTimeoutMs must be a positive timer-safe integer.');
     }
-    return this.requestJson<IDeconzSnapshot>('GET', '');
-  }
-
-  public async getGatewayConfig(): Promise<IDeconzGatewayConfig> {
-    if (this.config.snapshot?.config) {
-      return this.config.snapshot.config;
+    if (config.host !== undefined) this.endpoint = deconzEndpoint(config);
+    if (!config.snapshot && !this.endpoint) throw new Error('deCONZ host is required.');
+    if (config.apiKey !== undefined && (typeof config.apiKey !== 'string' || !config.apiKey.trim() || config.apiKey.trim() !== config.apiKey)) {
+      throw new Error('deCONZ API key must be a non-empty string.');
     }
-    return this.requestJson<IDeconzGatewayConfig>('GET', '/config');
+    if (config.websocketPort !== undefined) deconzPort(config.websocketPort);
+    if (config.bridgeId !== undefined && (typeof config.bridgeId !== 'string' || !config.bridgeId)) throw new Error('Invalid deCONZ configured gateway identity.');
+    if (config.enableWebSocket !== undefined && typeof config.enableWebSocket !== 'boolean') throw new Error('Invalid deCONZ WebSocket setting.');
   }
 
-  public async setLightState(lightIdArg: string, stateArg: IDeconzLightStatePatch): Promise<void> {
-    if (this.canUseHttp()) {
-      await this.put(`/lights/${encodeURIComponent(lightIdArg)}/state`, stateArg);
-    }
-    this.applyLightState(lightIdArg, stateArg);
+  public get isHealthy(): boolean {
+    return !this.lifetime.signal.aborted && !this.abortSignal?.aborted && this.streamHealthy && this.gatewayHealthy;
   }
 
-  public async setGroupState(groupIdArg: string, actionArg: IDeconzGroupActionPatch): Promise<void> {
-    if (this.canUseHttp()) {
-      await this.put(`/groups/${encodeURIComponent(groupIdArg)}/action`, actionArg);
-    }
-    this.applyGroupState(groupIdArg, actionArg);
+  public async getSnapshot(abortSignalArg?: AbortSignal): Promise<IDeconzSnapshot> {
+    try {
+      this.assertActive(abortSignalArg);
+      const snapshot = deconzSnapshot(this.config.snapshot ? structuredClone(this.config.snapshot) : await this.requestJson('GET', '', undefined, abortSignalArg));
+      this.assertGatewayIdentity(snapshot.config!);
+      this.gatewayHealthy = true;
+      return snapshot;
+    } catch (error) { this.gatewayHealthy = false; throw error; }
   }
 
-  public async setSensorConfig(sensorIdArg: string, configArg: IDeconzSensorConfigPatch): Promise<void> {
-    if (this.canUseHttp()) {
-      await this.put(`/sensors/${encodeURIComponent(sensorIdArg)}/config`, configArg);
-    }
-    this.applySensorConfig(sensorIdArg, configArg);
+  public async getGatewayConfig(abortSignalArg?: AbortSignal): Promise<IDeconzGatewayConfig> {
+    try {
+      this.assertActive(abortSignalArg);
+      const config = deconzGatewayConfig(this.config.snapshot ? this.config.snapshot.config : await this.requestJson('GET', '/config', undefined, abortSignalArg));
+      this.assertGatewayIdentity(config);
+      this.gatewayHealthy = true;
+      return config;
+    } catch (error) { this.gatewayHealthy = false; throw error; }
   }
 
-  public async setSensorState(sensorIdArg: string, stateArg: IDeconzSensorStatePatch): Promise<void> {
-    if (this.canUseHttp()) {
-      await this.put(`/sensors/${encodeURIComponent(sensorIdArg)}/state`, stateArg);
+  public async acquireApiKey(deviceTypeArg = 'smarthome.exchange', abortSignalArg?: AbortSignal): Promise<string> {
+    if (typeof deviceTypeArg !== 'string' || !deviceTypeArg || deviceTypeArg.length > 40) throw new Error('Invalid deCONZ client name.');
+    const result = await this.requestJson('POST', '', { devicetype: deviceTypeArg }, abortSignalArg, true);
+    if (!Array.isArray(result) || result.length !== 1 || !isDeconzRecord(result[0]) || !isDeconzRecord(result[0].success) || typeof result[0].success.username !== 'string' || !result[0].success.username.trim()) {
+      throw new Error('Invalid deCONZ pairing response.');
     }
-    this.applySensorState(sensorIdArg, stateArg);
+    return result[0].success.username;
   }
 
-  public async recallScene(groupIdArg: string, sceneIdArg: string): Promise<void> {
-    if (this.canUseHttp()) {
-      await this.put(`/groups/${encodeURIComponent(groupIdArg)}/scenes/${encodeURIComponent(sceneIdArg)}/recall`, {});
-    }
-    const group = this.config.snapshot?.groups[groupIdArg];
-    if (group) {
-      group.action = { ...group.action, scene: sceneIdArg };
-    }
+  public async setLightState(idArg: string, stateArg: IDeconzLightStatePatch, signalArg?: AbortSignal): Promise<void> {
+    const patch = deconzLightStatePatch(stateArg);
+    await this.put(`/lights/${this.resourceId(idArg)}/state`, patch, signalArg);
   }
 
-  public async put<TResult = unknown>(pathArg: string, dataArg: Record<string, unknown>): Promise<TResult> {
-    return this.requestJson<TResult>('PUT', pathArg, dataArg);
+  public async setGroupState(idArg: string, actionArg: IDeconzGroupActionPatch, signalArg?: AbortSignal): Promise<void> {
+    const patch = deconzGroupActionPatch(actionArg);
+    await this.put(`/groups/${this.resourceId(idArg)}/action`, patch, signalArg);
   }
 
-  public async post<TResult = unknown>(pathArg: string, dataArg: Record<string, unknown>): Promise<TResult> {
-    return this.requestJson<TResult>('POST', pathArg, dataArg);
+  public async setSensorConfig(idArg: string, configArg: IDeconzSensorConfigPatch, signalArg?: AbortSignal): Promise<void> {
+    const patch = deconzSensorConfigPatch(configArg);
+    await this.put(`/sensors/${this.resourceId(idArg)}/config`, patch, signalArg);
   }
 
-  public async subscribeToEvents(handlerArg: (eventArg: IDeconzWebsocketEvent) => void): Promise<() => Promise<void>> {
-    if (this.config.enableWebSocket === false || !this.config.host) {
-      return async () => {};
-    }
-
-    const WebSocketCtor = (globalThis as typeof globalThis & { WebSocket?: TWebSocketConstructor }).WebSocket;
-    if (!WebSocketCtor) {
-      return async () => {};
-    }
-
-    const websocketPort = await this.resolveWebSocketPort();
-    if (!websocketPort) {
-      return async () => {};
-    }
-
-    const socket = new WebSocketCtor(`ws://${this.config.host}:${websocketPort}`);
-    const listener = (messageArg: TWebSocketMessage) => {
-      const event = this.parseWebSocketMessage(messageArg.data);
-      if (event) {
-        handlerArg(event);
-      }
-    };
-
-    if (socket.addEventListener) {
-      socket.addEventListener('message', listener);
-    } else {
-      socket.onmessage = listener;
-    }
-
-    return async () => {
-      socket.close();
-    };
+  public async setSensorState(idArg: string, stateArg: IDeconzSensorStatePatch, signalArg?: AbortSignal): Promise<void> {
+    const snapshot = await this.getSnapshot(signalArg);
+    if (!snapshot.sensors[idArg]?.type?.startsWith('CLIP')) throw new Error('deCONZ sensor state is writable only for CLIP sensors.');
+    deconzSensorStatePatch(snapshot.sensors[idArg].type, stateArg);
+    await this.put(`/sensors/${this.resourceId(idArg)}/state`, stateArg, signalArg);
   }
 
-  public async destroy(): Promise<void> {}
-
-  private async requestJson<TResult>(methodArg: string, pathArg: string, dataArg?: Record<string, unknown>): Promise<TResult> {
-    if (!this.canUseHttp()) {
-      throw new Error('deCONZ host and apiKey are required when snapshot data is not provided.');
-    }
-
-    const response = await globalThis.fetch(`${this.baseUrl()}${this.apiPath(pathArg)}`, {
-      method: methodArg,
-      headers: dataArg ? { 'content-type': 'application/json' } : undefined,
-      body: dataArg ? JSON.stringify(dataArg) : undefined,
-    });
-    const text = await response.text();
-    const parsed = text ? JSON.parse(text) as unknown : undefined;
-
-    if (!response.ok) {
-      throw new Error(`deCONZ request ${methodArg} ${pathArg || '/'} failed with HTTP ${response.status}: ${text}`);
-    }
-
-    const apiError = this.findApiError(parsed);
-    if (apiError) {
-      throw new Error(`deCONZ request ${methodArg} ${pathArg || '/'} failed: ${apiError}`);
-    }
-
-    return parsed as TResult;
+  public async recallScene(groupIdArg: string, sceneIdArg: string, signalArg?: AbortSignal): Promise<void> {
+    await this.put(`/groups/${this.resourceId(groupIdArg)}/scenes/${this.resourceId(sceneIdArg)}/recall`, {}, signalArg);
   }
 
-  private baseUrl(): string {
-    const protocol = this.config.protocol || 'http';
-    const port = this.config.port ?? (protocol === 'https' ? 443 : 80);
-    const defaultPort = protocol === 'https' ? 443 : 80;
-    return `${protocol}://${this.config.host}${port === defaultPort ? '' : `:${port}`}`;
+  public async put<TResult = unknown>(pathArg: string, dataArg: Record<string, unknown>, signalArg?: AbortSignal): Promise<TResult> {
+    const result = await this.requestJson('PUT', pathArg, dataArg, signalArg);
+    this.assertWriteAcknowledgement(result, pathArg);
+    return result as TResult;
   }
 
-  private apiPath(pathArg: string): string {
-    const suffix = pathArg.startsWith('/') ? pathArg : pathArg ? `/${pathArg}` : '';
-    return `/api/${encodeURIComponent(String(this.config.apiKey))}${suffix}`;
+  public async post<TResult = unknown>(pathArg: string, dataArg: Record<string, unknown>, signalArg?: AbortSignal): Promise<TResult> {
+    const result = await this.requestJson('POST', pathArg, dataArg, signalArg);
+    this.assertWriteAcknowledgement(result);
+    return result as TResult;
   }
 
-  private canUseHttp(): boolean {
-    return Boolean(this.config.host && this.config.apiKey);
+  public async subscribeToEvents(handlerArg: (eventArg: IDeconzWebsocketEvent) => void, abortSignalArg?: AbortSignal, errorHandlerArg?: (errorArg: Error) => void): Promise<() => Promise<void>> {
+    this.assertActive(abortSignalArg);
+    if (this.config.enableWebSocket === false) return async () => {};
+    if (!this.endpoint) throw new Error('deCONZ WebSocket requires a live gateway endpoint.');
+    if (typeof globalThis.WebSocket !== 'function') throw new Error('deCONZ requires native WebSocket support.');
+    const port = this.config.websocketPort ?? (await this.getGatewayConfig(abortSignalArg)).websocketport;
+    this.assertActive(abortSignalArg);
+    if (port === undefined) throw new Error('deCONZ gateway did not advertise a WebSocket port.');
+    const websocketUrl = new URL(this.endpoint);
+    websocketUrl.protocol = 'ws:';
+    websocketUrl.port = String(deconzPort(port));
+    const socket = new WebSocket(websocketUrl);
+    const signal = AbortSignal.any([this.lifetime.signal, ...(this.abortSignal ? [this.abortSignal] : []), ...(abortSignalArg ? [abortSignalArg] : [])]);
+    let closing = false;
+    let closePromise: Promise<void> | undefined;
+    let opened = false;
+    let resolveOpen: () => void = () => {};
+    let rejectOpen: (reasonArg: Error) => void = () => {};
+    const ready = new Promise<void>((resolveArg, rejectArg) => { resolveOpen = resolveArg; rejectOpen = rejectArg; });
+    const report = (messageArg: string) => {
+      this.streamHealthy = false;
+      const error = new Error(messageArg);
+      if (!opened) rejectOpen(error);
+      else if (!closing) errorHandlerArg?.(error);
+    };
+    const message = (eventArg: MessageEvent<unknown>) => {
+      if (closing || signal.aborted) return;
+      let event: IDeconzWebsocketEvent;
+      try {
+        if (typeof eventArg.data !== 'string' || eventArg.data.length > 1048576) throw new Error('Invalid message.');
+        event = deconzWebsocketEvent(JSON.parse(eventArg.data) as unknown);
+      } catch { report('deCONZ WebSocket received an invalid event.'); return; }
+      handlerArg(event);
+    };
+    const onOpen = () => { opened = true; this.streamHealthy = true; resolveOpen(); };
+    const onError = () => report('deCONZ WebSocket connection failed.');
+    const onClose = () => {
+      if (!closing) report('deCONZ WebSocket connection closed.');
+      cleanup();
+    };
+    const onAbort = () => {
+      rejectOpen(new Error('deCONZ subscription cancelled.'));
+      void close().catch(() => {
+        this.streamHealthy = false;
+        errorHandlerArg?.(new Error('deCONZ WebSocket cleanup failed.'));
+      });
+    };
+    const cleanup = () => {
+      socket.removeEventListener('open', onOpen);
+      socket.removeEventListener('message', message);
+      socket.removeEventListener('error', onError);
+      socket.removeEventListener('close', onClose);
+      signal.removeEventListener('abort', onAbort);
+      this.subscriptions.delete(close);
+    };
+    const close = (): Promise<void> => {
+      if (closePromise) return closePromise;
+      closing = true;
+      socket.removeEventListener('message', message);
+      if (socket.readyState === WebSocket.CLOSED) { cleanup(); return Promise.resolve(); }
+      closePromise = new Promise<void>((resolveArg, rejectArg) => {
+        const closed = () => { clearTimeout(timer); socket.removeEventListener('close', closed); cleanup(); resolveArg(); };
+        const timer = setTimeout(() => {
+          socket.removeEventListener('close', closed);
+          closePromise = undefined;
+          rejectArg(new Error('deCONZ WebSocket close timed out.'));
+        }, this.timeoutMs);
+        socket.addEventListener('close', closed, { once: true });
+        socket.close();
+      });
+      return closePromise;
+    };
+    this.subscriptions.add(close);
+    socket.addEventListener('open', onOpen, { once: true });
+    socket.addEventListener('message', message);
+    socket.addEventListener('error', onError);
+    socket.addEventListener('close', onClose, { once: true });
+    signal.addEventListener('abort', onAbort, { once: true });
+    const timer = setTimeout(() => rejectOpen(new Error('deCONZ WebSocket open timed out.')), this.timeoutMs);
+    try {
+      if (signal.aborted) onAbort();
+      await ready;
+      this.assertActive(abortSignalArg);
+      return close;
+    } catch (error) {
+      await close();
+      throw error;
+    } finally { clearTimeout(timer); }
   }
 
-  private async resolveWebSocketPort(): Promise<number | undefined> {
-    if (this.config.websocketPort) {
-      return this.config.websocketPort;
-    }
-    if (this.config.snapshot?.config?.websocketport) {
-      return this.config.snapshot.config.websocketport;
-    }
-    if (!this.canUseHttp()) {
-      return undefined;
-    }
-    return (await this.getGatewayConfig()).websocketport;
+  public async destroy(): Promise<void> {
+    this.lifetime.abort();
+    const results = await Promise.allSettled([...this.subscriptions].map((closeArg) => closeArg()));
+    await Promise.allSettled([...this.operations]);
+    const failures = results.filter((resultArg): resultArg is PromiseRejectedResult => resultArg.status === 'rejected');
+    if (failures.length) throw new AggregateError(failures.map((failureArg) => failureArg.reason), 'deCONZ cleanup failed.');
   }
 
-  private parseWebSocketMessage(dataArg: unknown): IDeconzWebsocketEvent | undefined {
-    if (typeof dataArg === 'string') {
-      return JSON.parse(dataArg) as IDeconzWebsocketEvent;
-    }
-    if (this.isRecord(dataArg)) {
-      return dataArg as IDeconzWebsocketEvent;
-    }
-    return undefined;
+  private requestJson(methodArg: string, pathArg: string, dataArg?: Record<string, unknown>, signalArg?: AbortSignal, pairingArg = false): Promise<unknown> {
+    this.assertActive(signalArg);
+    if (!this.endpoint || !pairingArg && !this.config.apiKey) throw new Error('deCONZ live requests require a host and API key.');
+    if (pathArg && (!/^\/[a-z0-9/%_-]+$/i.test(pathArg) || pathArg.includes('..'))) throw new Error('Invalid deCONZ request path.');
+    const url = new URL(this.endpoint);
+    url.pathname = pairingArg ? '/api' : `/api/${encodeURIComponent(this.config.apiKey!)}${pathArg}`;
+    const operation = this.fetchJson(url, methodArg, dataArg, signalArg);
+    this.operations.add(operation);
+    void operation.then(() => this.operations.delete(operation), () => this.operations.delete(operation));
+    return operation;
   }
 
-  private applyLightState(lightIdArg: string, stateArg: IDeconzLightStatePatch): void {
-    const light = this.config.snapshot?.lights[lightIdArg];
-    if (light) {
-      light.state = { ...light.state, ...stateArg };
-    }
+  private async fetchJson(urlArg: URL, methodArg: string, dataArg?: Record<string, unknown>, signalArg?: AbortSignal): Promise<unknown> {
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), this.timeoutMs);
+    const signal = AbortSignal.any([deadline.signal, this.lifetime.signal, ...(this.abortSignal ? [this.abortSignal] : []), ...(signalArg ? [signalArg] : [])]);
+    try {
+      const response = await fetch(urlArg, { method: methodArg, redirect: 'error', signal, headers: dataArg ? { 'content-type': 'application/json' } : undefined, body: dataArg ? JSON.stringify(dataArg) : undefined });
+      if (!response.ok) {
+        await response.body?.cancel();
+        throw new DeconzRequestError(`deCONZ request failed with HTTP ${response.status}.`);
+      }
+      const reader = response.body?.getReader();
+      if (!reader) throw new DeconzRequestError('Empty deCONZ response.');
+      const chunks: Uint8Array[] = [];
+      let length = 0;
+      try {
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done) break;
+          length += chunk.value.length;
+          if (length > 8388608) { await reader.cancel(); throw new DeconzRequestError('deCONZ response exceeds the size limit.'); }
+          chunks.push(chunk.value);
+        }
+      } finally { reader.releaseLock(); }
+      const bytes = new Uint8Array(length);
+      let offset = 0;
+      for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
+      let result: unknown;
+      try { result = JSON.parse(new TextDecoder().decode(bytes)) as unknown; }
+      catch { throw new DeconzRequestError('Invalid deCONZ JSON response.'); }
+      if (Array.isArray(result)) {
+        for (const item of result) {
+          if (isDeconzRecord(item) && isDeconzRecord(item.error)) {
+            const type = typeof item.error.type === 'number' && Number.isInteger(item.error.type) ? item.error.type : undefined;
+            throw new DeconzRequestError('deCONZ rejected the request.', type);
+          }
+        }
+      }
+      return result;
+    } catch (error) {
+      if (signal.aborted) throw new DeconzRequestError(deadline.signal.aborted ? 'deCONZ request timed out.' : 'deCONZ request cancelled.');
+      if (error instanceof DeconzRequestError) throw error;
+      throw new DeconzRequestError('deCONZ network request failed.');
+    } finally { clearTimeout(timer); }
   }
 
-  private applyGroupState(groupIdArg: string, actionArg: IDeconzGroupActionPatch): void {
-    const group = this.config.snapshot?.groups[groupIdArg];
-    if (!group) {
-      return;
+  private assertWriteAcknowledgement(valueArg: unknown, pathArg?: string): void {
+    const entries = Array.isArray(valueArg) ? valueArg : [valueArg];
+    if (!entries.length || entries.some((entryArg) => !isDeconzRecord(entryArg) || !isDeconzRecord(entryArg.success) || !Object.keys(entryArg.success).length)) {
+      throw new Error('Invalid deCONZ write acknowledgement.');
     }
-    group.action = { ...group.action, ...actionArg };
-    if (typeof actionArg.on === 'boolean') {
-      group.state = {
-        ...group.state,
-        any_on: actionArg.on,
-        all_on: actionArg.on,
-      };
+    if (pathArg && entries.some((entryArg) => isDeconzRecord(entryArg) && isDeconzRecord(entryArg.success) && Object.keys(entryArg.success).some((addressArg) => addressArg !== pathArg && !addressArg.startsWith(`${pathArg}/`)))) {
+      throw new Error('deCONZ write acknowledgement addresses a different resource.');
     }
   }
 
-  private applySensorConfig(sensorIdArg: string, configArg: IDeconzSensorConfigPatch): void {
-    const sensor = this.config.snapshot?.sensors[sensorIdArg];
-    if (sensor) {
-      sensor.config = { ...sensor.config, ...configArg };
-    }
-  }
-
-  private applySensorState(sensorIdArg: string, stateArg: IDeconzSensorStatePatch): void {
-    const sensor = this.config.snapshot?.sensors[sensorIdArg];
-    if (sensor) {
-      sensor.state = { ...sensor.state, ...stateArg };
-    }
+  private assertActive(signalArg?: AbortSignal): void {
+    if (this.lifetime.signal.aborted || this.abortSignal?.aborted || signalArg?.aborted) throw new Error('deCONZ operation cancelled.');
   }
 
-  private findApiError(valueArg: unknown): string | undefined {
-    if (!Array.isArray(valueArg)) {
-      return undefined;
-    }
-    for (const item of valueArg) {
-      if (!this.isRecord(item) || !this.isRecord(item.error)) {
-        continue;
-      }
-      const description = item.error.description;
-      return typeof description === 'string' ? description : JSON.stringify(item.error);
+  private assertGatewayIdentity(configArg: IDeconzGatewayConfig): void {
+    const identity = (configArg.bridgeid ?? configArg.uuid)?.toLowerCase();
+    const expected = this.config.bridgeId?.toLowerCase();
+    if (expected && configArg.bridgeid?.toLowerCase() !== expected && configArg.uuid?.toLowerCase() !== expected || this.gatewayId && identity !== this.gatewayId) {
+      this.streamHealthy = false;
+      throw new Error('deCONZ gateway identity does not match configuration.');
     }
-    return undefined;
+    this.gatewayId = identity;
   }
 
-  private isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+  private resourceId(valueArg: string): string {
+    if (typeof valueArg !== 'string' || !/^[a-z0-9_-]+$/i.test(valueArg)) throw new Error('Invalid deCONZ resource identity.');
+    return encodeURIComponent(valueArg);
   }
 }