@smarthome.exchange/integrations 2.0.0 → 3.0.0

package/ts/integrations/deconz/deconz.classes.client.ts

@@ -1,291 +1,387 @@
-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';
+import * as plugins from '../../plugins.js';
+import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import { NativeIntegrationOwner, type INativeOperationLease } from '../../core/classes.nativeintegrationowner.js';
+import type { INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import type { IIntegrationSetupContext } from '../../core/types.js';
+import type { IDeconzConfig, IDeconzCredentialRequest, IDeconzGatewayConfig, IDeconzGroupActionPatch, IDeconzIntegrationOptions, IDeconzLightStatePatch, IDeconzSensorConfigPatch, IDeconzSensorStatePatch, IDeconzSnapshot, IDeconzWebsocketEvent, IDeconzWriteResult } from './deconz.types.js';
+import { captureDeconzOptions, deconzCurrentPatch, deconzData, deconzEndpoint, deconzGatewayConfig, deconzGroupActionPatch, deconzLightStatePatch, deconzPort, deconzSensorConfigPatch, deconzSensorStatePatch, deconzSnapshot, deconzText, deconzWebsocketEvent, isDeconzRecord, normalizeDeconzConfig } from './deconz.validation.js';
 
 export class DeconzRequestError extends Error {
   constructor(messageArg: string, public readonly apiErrorType?: number) { super(messageArg); }
 }
 
-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;
+export class DeconzWriteError extends Error {
+  public readonly effectOutcome = 'indeterminate' as const;
+  constructor() { super('deCONZ command was dispatched; its outcome is indeterminate.'); }
+}
 
-  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.');
-    }
-    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.');
-    }
-    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.');
-  }
+interface IDeconzOperation {
+  readonly lease: INativeOperationLease;
+  readonly signal: AbortSignal;
+  readonly deadline: number;
+  readonly actual: Set<Promise<unknown>>;
+}
 
-  public get isHealthy(): boolean {
-    return !this.lifetime.signal.aborted && !this.abortSignal?.aborted && this.streamHealthy && this.gatewayHealthy;
-  }
+export interface IDeconzClientOperation {
+  readonly isHealthy: boolean;
+  getSnapshot(signalArg?: AbortSignal): Promise<IDeconzSnapshot>;
+  setLightState(idArg: string, patchArg: IDeconzLightStatePatch, signalArg?: AbortSignal): Promise<IDeconzWriteResult>;
+  setGroupState(idArg: string, patchArg: IDeconzGroupActionPatch, signalArg?: AbortSignal): Promise<IDeconzWriteResult>;
+  setSensorConfig(idArg: string, patchArg: IDeconzSensorConfigPatch, signalArg?: AbortSignal): Promise<IDeconzWriteResult>;
+  setSensorState(idArg: string, patchArg: IDeconzSensorStatePatch, signalArg?: AbortSignal): Promise<IDeconzWriteResult>;
+}
 
-  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; }
-  }
+interface IDeconzSubscription {
+  close(retryArg?: boolean): Promise<void>;
+}
 
-  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; }
-  }
+/** Credentials and persistence resources are supplied by the independently selected host. */
+export class DeconzClient {
+  readonly #config: Readonly<IDeconzConfig>;
+  readonly #options: Readonly<IDeconzIntegrationOptions>;
+  readonly #context: INativeAdmissionContext;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #ownsOwner: boolean;
+  readonly #endpoint: URL;
+  readonly #lifetime: AbortController;
+  readonly #operations = new Set<Promise<unknown>>();
+  readonly #subscriptions = new Set<IDeconzSubscription>();
+  readonly #callbackFailures = new Set<Error>();
+  readonly #store?: NoSqlConfigStore;
+  readonly #ownsStore: boolean;
+  #closePromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
+  #streamHealthy = true;
+  #gatewayHealthy = false;
+  #onAbort?: () => void;
 
-  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.');
+  constructor(configArg: IDeconzConfig, contextArg: IIntegrationSetupContext, optionsArg: IDeconzIntegrationOptions = {}, ownerArg?: NativeIntegrationOwner) {
+    this.#config = normalizeDeconzConfig(configArg);
+    this.#options = captureDeconzOptions(optionsArg);
+    this.#ownsOwner = !ownerArg;
+    this.#owner = ownerArg ?? new NativeIntegrationOwner('deconz', { homeId: this.#options.homeId, capacity: this.#options.capacity });
+    this.#context = this.#owner.admission.admit(contextArg, this.#config.homeId);
+    if (this.#options.homeId !== undefined && this.#options.homeId !== this.#context.homeId) throw new Error('deCONZ constructor home does not match the host home.');
+    this.#endpoint = deconzEndpoint(this.#config);
+    if (this.#context.configStore && this.#options.db) throw new Error('deCONZ requires one selected credential store.');
+    this.#ownsStore = !this.#context.configStore && Boolean(this.#options.db);
+    if (this.#options.db && !(this.#options.db instanceof plugins.nosqldb.SmartdataDb)) throw new TypeError('deCONZ requires an actual caller-owned database.');
+    this.#store = this.#context.configStore ?? (this.#options.db && this.#options.keyProvider ? new NoSqlConfigStore({ db: this.#options.db, keyProvider: this.#options.keyProvider, homeId: this.#context.homeId, integrationDomain: 'deconz', timeoutMs: this.#config.requestTimeoutMs }) : undefined);
+    if (!this.#options.credentialProvider && !this.#store) throw new Error('deCONZ requires an explicit credential provider or an actual encrypted config store.');
+    this.#lifetime = new AbortController();
+    if (this.#context.abortSignal) {
+      this.#onAbort = () => { void this.destroy().catch(() => undefined); };
+      this.#context.abortSignal.addEventListener('abort', this.#onAbort, { once: true });
     }
-    return result[0].success.username;
   }
 
-  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 get isHealthy(): boolean { return !this.#closePromise && !this.#lifetime.signal.aborted && !this.#context.abortSignal?.aborted && !this.#owner.signal.aborted && this.#streamHealthy && this.#gatewayHealthy; }
+  public get canCreateCredential(): boolean { return Boolean(this.#options.credentialProvider?.create || !this.#options.credentialProvider && this.#store); }
 
-  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 getSnapshot(signalArg?: AbortSignal): Promise<IDeconzSnapshot> { return this.#run((operation) => this.#snapshot(operation), signalArg); }
+  public async getGatewayConfig(signalArg?: AbortSignal): Promise<IDeconzGatewayConfig> { return this.#run(async (operation) => (await this.#snapshot(operation)).config!, signalArg); }
 
-  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);
+  /** Keeps a runtime command, its actual callbacks, and its readback on one shared operation lease. */
+  public execute<TResult>(workArg: (clientArg: IDeconzClientOperation) => Promise<TResult>, signalArg?: AbortSignal): Promise<{ result: TResult; observation?: IDeconzWriteResult }> {
+    return this.#run(async (operation) => {
+      let open = true;
+      let written = false;
+      let selectedSnapshot: IDeconzSnapshot | undefined;
+      let observation: IDeconzWriteResult | undefined;
+      const check = (signal?: AbortSignal): void => { if (!open) throw new Error('deCONZ command session is closed.'); signal?.throwIfAborted(); this.#active(operation); };
+      const write = async (path: string, patch: Record<string, unknown>, signal?: AbortSignal): Promise<IDeconzWriteResult> => { check(signal); if (written) throw new Error('deCONZ command permits one write attempt.'); written = true; observation = await this.#write(operation, path, patch, selectedSnapshot); return observation; };
+      const session: IDeconzClientOperation = Object.freeze({
+        isHealthy: this.isHealthy,
+        getSnapshot: async (signal?: AbortSignal) => { check(signal); selectedSnapshot = await this.#snapshot(operation); return structuredClone(selectedSnapshot); },
+        setLightState: async (id: string, patch: IDeconzLightStatePatch, signal?: AbortSignal) => write(`/lights/${this.#resourceId(id)}/state`, deconzLightStatePatch(patch), signal),
+        setGroupState: async (id: string, patch: IDeconzGroupActionPatch, signal?: AbortSignal) => write(`/groups/${this.#resourceId(id)}/action`, deconzGroupActionPatch(patch), signal),
+        setSensorConfig: async (id: string, patch: IDeconzSensorConfigPatch, signal?: AbortSignal) => write(`/sensors/${this.#resourceId(id)}/config`, deconzSensorConfigPatch(patch), signal),
+        setSensorState: async (id: string, patch: IDeconzSensorStatePatch, signal?: AbortSignal) => write(`/sensors/${this.#resourceId(id)}/state`, this.#sensorPatch(patch), signal),
+      });
+      try { const result = await this.#foreign(operation, () => workArg(session)); return { result, observation }; }
+      finally { open = false; }
+    }, signalArg);
   }
 
-  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 acquireApiKey(deviceTypeArg = 'smarthome.exchange', signalArg?: AbortSignal): Promise<string> {
+    deconzText(deviceTypeArg, 'client name', 40);
+    return this.#run(async (operation) => {
+      this.#permission('config', this.#config.bridgeId, ['pair', 'credentials:create']);
+      if (!this.canCreateCredential) throw new Error('deCONZ pairing requires credential creation by the selected provider or encrypted store.');
+      await this.#basic(operation);
+      let dispatched = false;
+      try {
+        const result = await this.#request(operation, 'POST', '/api', { devicetype: deviceTypeArg }, () => { dispatched = true; });
+        if (!Array.isArray(result) || result.length !== 1 || !isDeconzRecord(result[0]) || !isDeconzRecord(result[0].success)) throw new Error('Invalid deCONZ pairing acknowledgement.');
+        return this.#key(result[0].success.username);
+      } catch (error) {
+        if (error instanceof DeconzRequestError && error.apiErrorType === 101) throw error;
+        if (dispatched) throw new DeconzWriteError();
+        throw error;
+      }
+    }, signalArg);
   }
 
-  public async recallScene(groupIdArg: string, sceneIdArg: string, signalArg?: AbortSignal): Promise<void> {
-    await this.put(`/groups/${this.resourceId(groupIdArg)}/scenes/${this.resourceId(sceneIdArg)}/recall`, {}, signalArg);
+  public createCredential(apiKeyArg: string, signalArg?: AbortSignal): Promise<void> {
+    const apiKey = this.#key(apiKeyArg);
+    return this.#run(async (operation) => {
+      this.#permission('config', this.#config.bridgeId, ['credentials:create']);
+      if (!this.canCreateCredential) throw new Error('deCONZ credential creation is unavailable.');
+      await this.#snapshot(operation, apiKey);
+      const request = this.#credentialRequest(operation);
+      let dispatched = false;
+      try {
+        if (this.#options.credentialProvider?.create) await this.#foreign(operation, () => { dispatched = true; return this.#options.credentialProvider!.create!(request, apiKey); });
+        else {
+          await this.#foreign(operation, () => this.#store!.initialize({ signal: operation.signal }));
+          await this.#foreign(operation, () => { dispatched = true; return this.#store!.create(this.#storeKey(), { version: 1, homeId: request.homeId, origin: request.origin, bridgeId: request.bridgeId, credentialReference: request.credentialReference, apiKey }); });
+        }
+        this.#active(operation);
+      } catch (error) { if (dispatched) throw new DeconzWriteError(); throw error; }
+    }, signalArg);
   }
 
-  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;
+  public async setLightState(idArg: string, patchArg: IDeconzLightStatePatch, signalArg?: AbortSignal): Promise<IDeconzWriteResult> { return this.put(`/lights/${this.#resourceId(idArg)}/state`, deconzLightStatePatch(patchArg), signalArg); }
+  public async setGroupState(idArg: string, patchArg: IDeconzGroupActionPatch, signalArg?: AbortSignal): Promise<IDeconzWriteResult> { return this.put(`/groups/${this.#resourceId(idArg)}/action`, deconzGroupActionPatch(patchArg), signalArg); }
+  public async setSensorConfig(idArg: string, patchArg: IDeconzSensorConfigPatch, signalArg?: AbortSignal): Promise<IDeconzWriteResult> { return this.put(`/sensors/${this.#resourceId(idArg)}/config`, deconzSensorConfigPatch(patchArg), signalArg); }
+  public async setSensorState(idArg: string, patchArg: IDeconzSensorStatePatch, signalArg?: AbortSignal): Promise<IDeconzWriteResult> { return this.put(`/sensors/${this.#resourceId(idArg)}/state`, this.#sensorPatch(patchArg), signalArg); }
+  public async recallScene(groupIdArg: string, sceneIdArg: string, signalArg?: AbortSignal): Promise<IDeconzWriteResult> { return this.put(`/groups/${this.#resourceId(groupIdArg)}/scenes/${this.#resourceId(sceneIdArg)}/recall`, {}, signalArg); }
+  public async put(pathArg: string, dataArg: Record<string, unknown>, signalArg?: AbortSignal): Promise<IDeconzWriteResult> {
+    const match = /^\/(lights|groups|sensors)\/([a-z0-9_-]+)\/(state|action|config)$/i.exec(pathArg);
+    const scene = /^\/groups\/([a-z0-9_-]+)\/scenes\/([a-z0-9_-]+)\/recall$/i.exec(pathArg);
+    if (!match && !scene) throw new Error('Unsupported deCONZ command path.');
+    const patch = scene ? deconzData(dataArg, []) : match![1] === 'lights' && match![3] === 'state' ? deconzLightStatePatch(dataArg) : match![1] === 'groups' && match![3] === 'action' ? deconzGroupActionPatch(dataArg) : match![1] === 'sensors' && match![3] === 'config' ? deconzSensorConfigPatch(dataArg) : match![1] === 'sensors' && match![3] === 'state' ? this.#sensorPatch(dataArg) : undefined;
+    if (!patch) throw new Error('Unsupported deCONZ command endpoint.');
+    return this.#run((operation) => this.#write(operation, pathArg, patch), signalArg);
   }
-
-  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;
+  public async post(pathArg: string, dataArg: Record<string, unknown>, signalArg?: AbortSignal): Promise<never> {
+    void pathArg; void dataArg; void signalArg;
+    throw new Error('deCONZ arbitrary creation requires a supported current control contract.');
   }
 
-  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;
+  public subscribeToEvents(handlerArg: (eventArg: IDeconzWebsocketEvent) => unknown, signalArg?: AbortSignal, errorHandlerArg?: (errorArg: Error) => unknown): Promise<() => Promise<void>> {
+    if (typeof handlerArg !== 'function' || errorHandlerArg !== undefined && typeof errorHandlerArg !== 'function') throw new TypeError('deCONZ subscriber requires data functions.');
+    let resolveSubscription: (closeArg: () => Promise<void>) => void = () => {};
+    let rejectSubscription: (errorArg: unknown) => void = () => {};
+    let issued = false;
+    const subscribed = new Promise<() => Promise<void>>((resolve, reject) => { resolveSubscription = resolve; rejectSubscription = reject; });
+    let admitted: Promise<void>;
+    try { admitted = this.#run(async (operation) => {
+      if (this.#config.enableWebSocket === false) { issued = true; resolveSubscription(async () => {}); return; }
+      const config = (await this.#snapshot(operation)).config!;
+      const port = config.websocketport;
+      if (port === undefined) throw new Error('deCONZ gateway did not advertise a WebSocket port.');
+      this.#active(operation);
+      if (typeof globalThis.WebSocket !== 'function') throw new Error('deCONZ requires native WebSocket support.');
+      const url = new URL(this.#endpoint); url.protocol = 'ws:'; url.port = String(deconzPort(port));
+      const signal = AbortSignal.any([this.#lifetime.signal, this.#owner.signal, ...(this.#context.abortSignal ? [this.#context.abortSignal] : []), ...(signalArg ? [signalArg] : [])]);
+      const callbacks = new Set<Promise<unknown>>();
+      let closing = false; let opened = false; let closePromise: Promise<void> | undefined; let closeFailed = false;
+      let resolveOpen: () => void = () => {}; let rejectOpen: (errorArg: Error) => void = () => {};
+      const ready = new Promise<void>((resolve, reject) => { resolveOpen = resolve; rejectOpen = reject; });
+      // Keep the subscription's actual lifetime on the shared lease after the caller receives its close handle.
+      let releaseLifetime: () => void = () => {};
+      const lifetime = new Promise<void>((resolve) => { releaseLifetime = resolve; });
+      operation.actual.add(lifetime);
+      void lifetime.then(() => operation.actual.delete(lifetime));
+      let socket: WebSocket;
+      try { socket = new WebSocket(url); } catch { releaseLifetime(); throw new Error('deCONZ WebSocket allocation failed.'); }
+      const cleanup = (): void => {
+        socket.removeEventListener('open', onOpen); socket.removeEventListener('message', message); socket.removeEventListener('error', onError); socket.removeEventListener('close', onClose); signal.removeEventListener('abort', onAbort);
+      };
+      const subscription: IDeconzSubscription = { close: (retryArg = false) => {
+        if (retryArg && closeFailed) { closePromise = undefined; closeFailed = false; }
+        if (!closePromise) {
+          closing = true;
+          closePromise = Promise.resolve().then(async () => {
+            const closed = socket.readyState === WebSocket.CLOSED ? Promise.resolve() : new Promise<void>((resolve, reject) => {
+              const done = (): void => { clearTimeout(timer); socket.removeEventListener('close', done); resolve(); };
+              const timer = setTimeout(() => { socket.removeEventListener('close', done); reject(new Error('deCONZ WebSocket close timed out.')); }, this.#config.requestTimeoutMs);
+              socket.addEventListener('close', done, { once: true });
+              try { socket.close(); } catch { clearTimeout(timer); socket.removeEventListener('close', done); reject(new Error('deCONZ WebSocket close failed.')); }
+            });
+            const [closedResult] = await Promise.allSettled([closed, ...callbacks]);
+            const errors = closedResult.status === 'rejected' ? [closedResult] : [];
+            if (errors.length) throw new AggregateError(errors.map(() => new Error('deCONZ subscription cleanup failed.')), 'deCONZ subscription cleanup failed.');
+            cleanup(); this.#subscriptions.delete(subscription);
+          });
+          void closePromise.then(releaseLifetime, () => { closeFailed = true; releaseLifetime(); });
+        }
+        return closePromise;
+      } };
+      this.#subscriptions.add(subscription);
+      const invoke = (work: () => unknown): void => {
+        if (closing || signal.aborted) return;
+        let callback: Promise<unknown>;
+        try { callback = this.#run((leaseOperation) => this.#foreign(leaseOperation, async () => {
+          try { await work(); } catch { this.#callbackFailures.add(new Error('deCONZ subscriber failed.')); this.#streamHealthy = false; throw new Error('deCONZ subscriber failed.'); }
+        })); }
+        catch { this.#callbackFailures.add(new Error('deCONZ subscriber admission failed.')); this.#streamHealthy = false; return; }
+        callbacks.add(callback);
+        void callback.then(() => callbacks.delete(callback), () => { callbacks.delete(callback); if (!closing && !signal.aborted) { this.#callbackFailures.add(new Error('deCONZ subscriber failed.')); this.#streamHealthy = false; } });
+      };
+      const report = (messageArg: string): void => { this.#streamHealthy = false; const error = new Error(messageArg); if (!opened) rejectOpen(error); else if (errorHandlerArg) invoke(() => errorHandlerArg(error)); };
+      const message = (eventArg: MessageEvent<unknown>): void => {
+        if (closing || signal.aborted) return;
+        try {
+          if (typeof eventArg.data !== 'string' || eventArg.data.length > 1048576) throw new Error('Invalid deCONZ event.');
+          const event = deconzWebsocketEvent(JSON.parse(eventArg.data) as unknown);
+          invoke(() => handlerArg(event));
+        } catch { report('deCONZ WebSocket received an invalid event.'); }
+      };
+      const onOpen = (): void => { opened = true; this.#streamHealthy = true; resolveOpen(); };
+      const onError = (): void => report('deCONZ WebSocket connection failed.');
+      const onClose = (): void => { if (!closing) { report('deCONZ WebSocket connection closed.'); void subscription.close().catch(() => { this.#streamHealthy = false; }); } };
+      const onAbort = (): void => { rejectOpen(new Error('deCONZ subscription cancelled.')); void subscription.close().catch(() => { this.#streamHealthy = false; }); };
+      const onDeadline = (): void => rejectOpen(this.#cancelled(operation));
+      socket.addEventListener('open', onOpen, { once: true }); socket.addEventListener('message', message); socket.addEventListener('error', onError); socket.addEventListener('close', onClose); signal.addEventListener('abort', onAbort, { once: true });
+      operation.signal.addEventListener('abort', onDeadline, { once: true });
       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); }
+        await this.#foreign(operation, () => ready);
+        this.#active(operation);
+        if (signal.aborted) throw new Error('deCONZ subscription cancelled.');
+        issued = true;
+        resolveSubscription(async () => { await subscription.close(); await admitted; });
+      } catch (error) { await subscription.close(); throw error; }
+      finally { operation.signal.removeEventListener('abort', onDeadline); }
+    }, signalArg); } catch (error) { rejectSubscription(error); return subscribed; }
+    void admitted.then(() => { if (!issued) rejectSubscription(new Error('deCONZ subscription failed.')); }, (error: unknown) => { if (!issued) rejectSubscription(error); else { this.#callbackFailures.add(new Error('deCONZ subscription lifecycle failed.')); this.#streamHealthy = false; } });
+    return subscribed;
   }
 
-  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.');
+  public destroy(): Promise<void> {
+    if (!this.#closePromise) {
+      this.#closePromise = Promise.resolve().then(() => this.#drain(false));
+      this.#lifetime.abort();
+      if (this.#onAbort) this.#context.abortSignal!.removeEventListener('abort', this.#onAbort);
+    }
+    return this.#closePromise;
+  }
+  public retryCleanup(): Promise<void> {
+    if (!this.#closePromise) throw new Error('deCONZ cleanup retry requires a terminal client.');
+    if (!this.#retryPromise) {
+      this.#retryPromise = Promise.resolve().then(async () => { await this.#closePromise!.catch(() => undefined); await this.#drain(true); });
+      const settled = (): void => { this.#retryPromise = undefined; };
+      void this.#retryPromise.then(settled, settled);
+    }
+    return this.#retryPromise;
+  }
+  async #drain(retryArg: boolean): Promise<void> {
+    if (retryArg) this.#callbackFailures.clear();
+    const results = await Promise.allSettled([...this.#subscriptions].map((subscription) => subscription.close(retryArg)));
+    await Promise.allSettled([...this.#operations]);
+    const other = await Promise.allSettled([...(this.#ownsStore && this.#store ? [retryArg ? this.#store.retryCleanup() : this.#store.close()] : []), ...(this.#ownsOwner ? [retryArg ? this.#owner.retryCleanup() : this.#owner.close()] : [])]);
+    const errors = [...results, ...other].filter((result): result is PromiseRejectedResult => result.status === 'rejected').map(() => new Error('deCONZ cleanup failed.'));
+    errors.push(...this.#callbackFailures);
+    if (errors.length) throw new AggregateError(errors, 'deCONZ cleanup failed; handles remain retained for explicit retry.');
   }
 
-  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));
+  #run<TResult>(workArg: (operationArg: IDeconzOperation) => Promise<TResult>, signalArg?: AbortSignal): Promise<TResult> {
+    if (this.#closePromise || this.#lifetime.signal.aborted) throw new DeconzRequestError('deCONZ request cancelled.');
+    const operation = this.#owner.runOperation(this.#context, this.#config.homeId, async (lease) => {
+      const deadlineAbort = new AbortController();
+      const deadline = performance.now() + this.#config.requestTimeoutMs!;
+      const signal = AbortSignal.any([lease.signal, this.#lifetime.signal, deadlineAbort.signal, ...(signalArg ? [signalArg] : [])]);
+      const actual = new Set<Promise<unknown>>();
+      lease.own(async () => { while (actual.size) await Promise.allSettled([...actual]); });
+      const timer = setTimeout(() => deadlineAbort.abort(new DeconzRequestError('deCONZ request timed out.')), this.#config.requestTimeoutMs);
+      try { return await workArg({ lease, signal, deadline, actual }); }
+      finally { clearTimeout(timer); }
+    });
+    this.#operations.add(operation);
+    void operation.then(() => this.#operations.delete(operation), () => this.#operations.delete(operation));
     return operation;
   }
-
-  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] : [])]);
+  async #foreign<TResult>(operationArg: IDeconzOperation, workArg: () => Promise<TResult>, transportArg = false): Promise<TResult> {
+    this.#active(operationArg);
+    if (operationArg.actual.size >= 16) throw new Error('deCONZ actual callback capacity reached.');
+    const actual = Promise.resolve().then(() => { this.#active(operationArg); return workArg(); });
+    operationArg.actual.add(actual);
+    void actual.then(() => operationArg.actual.delete(actual), () => operationArg.actual.delete(actual));
+    let abort: () => void = () => {};
+    const cancelled = new Promise<never>((resolve, reject) => { void resolve; abort = () => reject(this.#cancelled(operationArg)); operationArg.signal.addEventListener('abort', abort, { once: true }); if (operationArg.signal.aborted) abort(); });
+    try { const result = await Promise.race([actual, cancelled]); this.#active(operationArg); return result; }
+    catch (error) { if (operationArg.signal.aborted) throw this.#cancelled(operationArg); if (error instanceof DeconzWriteError) throw new DeconzWriteError(); if (transportArg && error instanceof DeconzRequestError) throw error; throw new Error('deCONZ operation failed.'); }
+    finally { operationArg.signal.removeEventListener('abort', abort); }
+  }
+  #active(operationArg: IDeconzOperation): void { if (operationArg.signal.aborted || performance.now() >= operationArg.deadline || this.#closePromise) throw this.#cancelled(operationArg); operationArg.lease.assertOpen(); }
+  #cancelled(operationArg: IDeconzOperation): DeconzRequestError { return new DeconzRequestError(performance.now() >= operationArg.deadline || operationArg.signal.reason instanceof DeconzRequestError && operationArg.signal.reason.message === 'deCONZ request timed out.' ? 'deCONZ request timed out.' : 'deCONZ request cancelled.'); }
+  #credentialRequest(operationArg: IDeconzOperation): IDeconzCredentialRequest { return Object.freeze({ homeId: this.#context.homeId, origin: this.#endpoint.origin, bridgeId: this.#config.bridgeId, credentialReference: this.#config.credentialReference, signal: operationArg.signal, deadline: operationArg.deadline }); }
+  #storeKey(): string { return `deconz.credential.${encodeURIComponent(this.#config.credentialReference)}`; }
+  async #credential(operationArg: IDeconzOperation): Promise<string> {
+    const request = this.#credentialRequest(operationArg);
+    if (this.#options.credentialProvider) return this.#key(await this.#foreign(operationArg, () => this.#options.credentialProvider!.resolve(request)));
+    await this.#foreign(operationArg, () => this.#store!.initialize({ signal: operationArg.signal }));
+    const envelope = deconzData(await this.#foreign(operationArg, () => this.#store!.get(this.#storeKey())), ['version', 'homeId', 'origin', 'bridgeId', 'credentialReference', 'apiKey']);
+    if (envelope.version !== 1 || envelope.homeId !== request.homeId || envelope.origin !== request.origin || envelope.bridgeId !== request.bridgeId || envelope.credentialReference !== request.credentialReference) throw new Error('deCONZ credential reference does not match the selected home and bridge.');
+    return this.#key(envelope.apiKey);
+  }
+  #key(valueArg: unknown): string { return deconzText(valueArg, 'resolved credential', 256); }
+  async #basic(operationArg: IDeconzOperation): Promise<IDeconzGatewayConfig> { const config = deconzGatewayConfig(await this.#request(operationArg, 'GET', '/api/config')); this.#identity(config); return config; }
+  async #snapshot(operationArg: IDeconzOperation, keyArg?: string): Promise<IDeconzSnapshot> {
     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); }
+      await this.#basic(operationArg);
+      const key = keyArg ?? await this.#credential(operationArg);
+      const snapshot = deconzSnapshot(await this.#request(operationArg, 'GET', `/api/${encodeURIComponent(key)}`));
+      this.#identity(snapshot.config!); this.#active(operationArg); this.#gatewayHealthy = true;
+      return { ...snapshot, homeId: this.#context.homeId };
+    } catch (error) { this.#gatewayHealthy = false; throw error; }
   }
-
-  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.');
-    }
-    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.');
-    }
+  #identity(configArg: IDeconzGatewayConfig): void { if (configArg.bridgeid?.toLowerCase() !== this.#config.bridgeId && configArg.uuid?.toLowerCase() !== this.#config.bridgeId) { this.#streamHealthy = false; throw new Error('deCONZ gateway identity does not match configuration.'); } }
+  #permission(resourceArg: string, idArg: string, fieldsArg: readonly string[]): void {
+    if (!this.#options.controlPermissions?.some((permission) => permission.resource === resourceArg && permission.resourceId === idArg && fieldsArg.every((field) => permission.fields.includes(field)))) throw new Error('deCONZ control requires exact owner authorization.');
   }
-
-  private assertActive(signalArg?: AbortSignal): void {
-    if (this.lifetime.signal.aborted || this.abortSignal?.aborted || signalArg?.aborted) throw new Error('deCONZ operation cancelled.');
+  #sensorPatch(valueArg: unknown): Record<string, unknown> {
+    return deconzData(valueArg, ['alarm', 'battery', 'carbonmonoxide', 'consumption', 'current', 'dark', 'daylight', 'fire', 'flag', 'humidity', 'lightlevel', 'lux', 'open', 'power', 'presence', 'duration', 'pressure', 'status', 'temperature', 'vibration', 'voltage', 'water', 'buttonevent']);
   }
-
-  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.');
+  async #write(operationArg: IDeconzOperation, pathArg: string, patchArg: Record<string, unknown>, selectedArg?: IDeconzSnapshot): Promise<IDeconzWriteResult> {
+    await this.#basic(operationArg);
+    const key = await this.#credential(operationArg);
+    const snapshot = await this.#snapshot(operationArg, key);
+    const parts = pathArg.split('/');
+    const resource = parts[1]; const id = parts[2]; const section = parts[3];
+    if (selectedArg && (resource === 'lights' || resource === 'sensors')) {
+      const current = snapshot[resource][id]; const selected = selectedArg[resource][id];
+      if (!selected || !current || selected.uniqueid !== current.uniqueid || selected.type !== current.type) throw new Error('deCONZ selected resource changed before dispatch.');
     }
-    this.gatewayId = identity;
+    if (selectedArg && resource === 'groups' && JSON.stringify(selectedArg.groups[id]?.lights) !== JSON.stringify(snapshot.groups[id]?.lights)) throw new Error('deCONZ selected group membership changed before dispatch.');
+    if (section === 'scenes') {
+      this.#permission('scenes', `${id}/${parts[4]}`, ['recall']);
+      if (snapshot.config?.rfconnected === false || !snapshot.groups[id]?.lights?.length || !Object.values(snapshot.groups[id].scenes ?? {}).some((scene) => scene.id === parts[4])) throw new Error('deCONZ scene is not currently available.');
+    } else {
+      this.#permission(resource, id, Object.keys(patchArg));
+      if (resource === 'sensors' && section === 'state') deconzSensorStatePatch(snapshot.sensors[id]?.type, patchArg);
+      deconzCurrentPatch(snapshot, resource as 'lights' | 'groups' | 'sensors', id, section as 'state' | 'action' | 'config', patchArg);
+    }
+    let dispatched = false;
+    try {
+      const result = await this.#request(operationArg, 'PUT', `/api/${encodeURIComponent(key)}${pathArg}`, patchArg, () => { dispatched = true; });
+      this.#acknowledgement(result, pathArg);
+      const observedState = await this.#snapshot(operationArg);
+      return { effectOutcome: 'accepted', observedState, causalityConfirmed: false, physicalCompletion: 'unconfirmed' };
+    } catch (error) { this.#gatewayHealthy = false; if (dispatched) throw new DeconzWriteError(); throw error; }
   }
-
-  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);
+  #resourceId(valueArg: string): string { if (typeof valueArg !== 'string' || !/^[a-z0-9_-]+$/i.test(valueArg)) throw new Error('Invalid deCONZ resource identity.'); return valueArg; }
+  #acknowledgement(valueArg: unknown, pathArg: string): void {
+    const entries = Array.isArray(valueArg) ? valueArg : [valueArg];
+    if (!entries.length || entries.some((entry) => !isDeconzRecord(entry) || !isDeconzRecord(entry.success) || !Object.keys(entry.success).length || Object.keys(entry.success).some((address) => address !== pathArg && !address.startsWith(`${pathArg}/`)))) throw new Error('Invalid deCONZ write acknowledgement.');
+  }
+  async #request(operationArg: IDeconzOperation, methodArg: string, pathArg: string, dataArg?: Record<string, unknown>, dispatchArg?: () => void): Promise<unknown> {
+    const url = new URL(this.#endpoint); url.pathname = pathArg;
+    return this.#foreign(operationArg, async () => {
+      try {
+        dispatchArg?.();
+        const response = await fetch(url, { method: methodArg, redirect: 'error', signal: operationArg.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)) throw new DeconzRequestError('deCONZ rejected the request.', typeof item.error.type === 'number' && Number.isInteger(item.error.type) ? item.error.type : undefined);
+        return result;
+      } catch (error) { if (operationArg.signal.aborted) throw this.#cancelled(operationArg); if (error instanceof DeconzRequestError) throw error; throw new DeconzRequestError('deCONZ network request failed.'); }
+    }, true);
   }
 }