@smarthome.exchange/integrations 0.2.0 → 1.0.0

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);
   }
 }

package/ts/integrations/deconz/deconz.classes.configflow.ts

@@ -1,39 +1,48 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { DeconzClient, DeconzRequestError } from './deconz.classes.client.js';
 import type { IDeconzConfig } from './deconz.types.js';
 
 export class DeconzConfigFlow implements IConfigFlow<IDeconzConfig> {
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IDeconzConfig>> {
     void contextArg;
+    const submit = async (valuesArg: Record<string, unknown>): Promise<IConfigFlowStep<IDeconzConfig>> => {
+      let client: DeconzClient | undefined;
+      try {
+        const host = valuesArg.host ?? candidateArg.host;
+        if (typeof host !== 'string' || !host) throw new Error('Host is required.');
+        if (valuesArg.apiKey !== undefined && typeof valuesArg.apiKey !== 'string') throw new Error('API key must be a string.');
+        if (valuesArg.port !== undefined && typeof valuesArg.port !== 'number') throw new Error('Port must be a number.');
+        const protocol = valuesArg.protocol ?? 'http';
+        if (protocol !== 'http' && protocol !== 'https') throw new Error('Protocol must be http or https.');
+        const config: IDeconzConfig = { host, port: valuesArg.port as number | undefined ?? candidateArg.port, protocol, apiKey: typeof valuesArg.apiKey === 'string' && valuesArg.apiKey ? valuesArg.apiKey : undefined };
+        client = new DeconzClient(config);
+        if (!config.apiKey) {
+          config.apiKey = await client.acquireApiKey();
+          await client.destroy();
+          client = new DeconzClient(config);
+        }
+        const snapshot = await client.getSnapshot();
+        if (candidateArg.id && snapshot.config?.bridgeid && candidateArg.id.replace(/[^a-f0-9]/gi, '').toUpperCase() !== snapshot.config.bridgeid.toUpperCase()) {
+          throw new Error('deCONZ gateway identity does not match discovery.');
+        }
+        config.bridgeId = snapshot.config?.bridgeid ?? snapshot.config?.uuid;
+        return { kind: 'done', title: 'deCONZ connected', config };
+      } catch (error) {
+        if (error instanceof DeconzRequestError && error.apiErrorType === 101) {
+          return { kind: 'wait', title: 'Unlock deCONZ', description: 'In Phoscon, open Gateway → Advanced → Authenticate app, then retry within 60 seconds.', submit: () => submit(valuesArg) };
+        }
+        return { kind: 'error', title: 'deCONZ connection failed', error: error instanceof Error ? error.message : 'deCONZ setup failed.' };
+      } finally { await client?.destroy(); }
+    };
     return {
-      kind: 'form',
-      title: 'Connect deCONZ Gateway',
-      description: 'Configure the local deCONZ REST API endpoint. Leave API key empty only if setup will use a snapshot fixture.',
+      kind: 'form', title: 'Connect deCONZ Gateway',
+      description: 'Provide a gateway API key, or leave it empty to pair after unlocking Authenticate app in Phoscon.',
       fields: [
         { name: 'host', label: 'Host', type: 'text', required: true },
         { name: 'port', label: 'Port', type: 'number' },
+        { name: 'protocol', label: 'Protocol', type: 'select', options: [{ label: 'HTTP', value: 'http' }, { label: 'HTTPS', value: 'https' }] },
         { name: 'apiKey', label: 'API key', type: 'password' },
-      ],
-      submit: async (valuesArg) => {
-        const host = String(valuesArg.host || candidateArg.host || '');
-        if (!host) {
-          return {
-            kind: 'error',
-            title: 'deCONZ configuration incomplete',
-            error: 'Host is required.',
-          };
-        }
-        return {
-          kind: 'done',
-          title: 'deCONZ configured',
-          config: {
-            bridgeId: candidateArg.id,
-            host,
-            port: typeof valuesArg.port === 'number' ? valuesArg.port : candidateArg.port || 80,
-            apiKey: valuesArg.apiKey ? String(valuesArg.apiKey) : undefined,
-            protocol: 'http',
-          },
-        };
-      },
+      ], submit,
     };
   }
 }