@smarthome.exchange/integrations 2.0.0 → 4.0.0

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

@@ -1,48 +1,76 @@
+import { NativeIntegrationOwner, NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 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';
+import { DeconzClient, DeconzRequestError, DeconzWriteError } from './deconz.classes.client.js';
+import type { IDeconzConfig, IDeconzIntegrationOptions } from './deconz.types.js';
+import { captureDeconzOptions, deconzBridgeId, deconzData, deconzText, normalizeDeconzConfig } from './deconz.validation.js';
 
 export class DeconzConfigFlow implements IConfigFlow<IDeconzConfig> {
+  readonly #options: Readonly<IDeconzIntegrationOptions>;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #scope: NativeIntegrationScope;
+  readonly #ownsOwner: boolean;
+  #terminal = false;
+  #submitted = false;
+
+  constructor(optionsArg: IDeconzIntegrationOptions = {}, ownerArg?: NativeIntegrationOwner) {
+    this.#options = captureDeconzOptions(optionsArg);
+    this.#ownsOwner = !ownerArg;
+    this.#owner = ownerArg ?? new NativeIntegrationOwner('deconz', { homeId: this.#options.homeId, capacity: this.#options.capacity });
+    this.#scope = this.#owner.createFlowScope();
+  }
+
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IDeconzConfig>> {
-    void contextArg;
+    const context = this.#scope.admit(contextArg);
+    if (this.#terminal) throw new Error('deCONZ config flow is closed.');
+    const candidate = deconzData(candidateArg, ['id', 'source', 'host', 'port', 'name', 'integrationDomain', 'manufacturer', 'model', 'serialNumber', 'macAddress', 'metadata']);
+    // Discovery reports a selection hint; only current gateway reads can check that reported identity.
+    const bridgeId = deconzBridgeId(candidate.id);
+    const host = deconzText(candidate.host, 'discovered host');
+    const port = candidate.port;
+    if (port !== undefined && typeof port !== 'number') throw new TypeError('Invalid deCONZ discovered port.');
     const submit = async (valuesArg: Record<string, unknown>): Promise<IConfigFlowStep<IDeconzConfig>> => {
-      let client: DeconzClient | undefined;
+      if (this.#terminal || this.#submitted) return { kind: 'error', title: 'deCONZ flow closed', error: 'deCONZ config flow is closed or already submitting.' };
+      this.#submitted = true;
+      let effectAccepted = false;
+      let capturedValues: Record<string, unknown> | 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 };
+        const values = deconzData(valuesArg, ['host', 'port', 'protocol', 'credentialReference', 'apiKey']);
+        capturedValues = Object.freeze(values);
+        const config = normalizeDeconzConfig({ homeId: context.homeId, host: values.host ?? host, ...(values.port !== undefined || port !== undefined ? { port: values.port ?? port } : {}), protocol: values.protocol ?? 'http', bridgeId, credentialReference: deconzText(values.credentialReference, 'credential reference') });
+        const suppliedKey = values.apiKey === undefined || values.apiKey === '' ? undefined : deconzText(values.apiKey, 'pairing credential', 256);
+        const result = await this.#scope.run(context, context.homeId, async (lease) => {
+          const client = new DeconzClient(config, lease.context, this.#options, this.#owner);
+          let cleanupStarted = false;
+          lease.own(() => { if (cleanupStarted) return client.retryCleanup(); cleanupStarted = true; return client.destroy(); });
+          if (!client.canCreateCredential) throw new Error('deCONZ flow requires credential creation by the selected provider or encrypted store.');
+          const key = suppliedKey ?? await client.acquireApiKey(undefined, lease.signal);
+          effectAccepted = !suppliedKey;
+          await client.createCredential(key, lease.signal);
+          lease.assertOpen();
+          return { kind: 'done', title: 'deCONZ connected', config } as IConfigFlowStep<IDeconzConfig>;
+        });
+        this.#terminal = true;
+        await this.#scope.close();
+        return result;
       } 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) };
+        if (error instanceof DeconzRequestError && error.apiErrorType === 101 && !effectAccepted) {
+          return { kind: 'wait', title: 'Unlock deCONZ', description: 'In Phoscon, open Gateway → Advanced → Authenticate app, then retry within 60 seconds.', submit: () => submit(capturedValues!) };
         }
-        return { kind: 'error', title: 'deCONZ connection failed', error: error instanceof Error ? error.message : 'deCONZ setup failed.' };
-      } finally { await client?.destroy(); }
+        if (effectAccepted || error instanceof DeconzWriteError) { this.#terminal = true; await this.#scope.close(); }
+        return { kind: 'error', title: 'deCONZ connection failed', error: effectAccepted || error instanceof DeconzWriteError ? 'deCONZ pairing was dispatched; do not replay pairing.' : 'deCONZ setup failed.' };
+      } finally { this.#submitted = false; }
     };
     return {
-      kind: 'form', title: 'Connect deCONZ Gateway',
-      description: 'Provide a gateway API key, or leave it empty to pair after unlocking Authenticate app in Phoscon.',
+      kind: 'form', title: 'Connect deCONZ Gateway', description: 'Select a credential reference. A new API key is validated and stored by the host credential provider or encrypted config store.',
       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: 'credentialReference', label: 'Credential reference', type: 'text', required: true },
         { name: 'apiKey', label: 'API key', type: 'password' },
       ], submit,
     };
   }
+  public destroy(): Promise<void> { this.#terminal = true; return this.#ownsOwner ? this.#owner.close() : this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#ownsOwner ? this.#owner.retryCleanup() : this.#scope.retryCleanup(); }
 }

package/ts/integrations/deconz/deconz.classes.integration.ts

@@ -1,11 +1,13 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
-import { DeconzClient } from './deconz.classes.client.js';
+import { DeconzClient, DeconzWriteError, type IDeconzClientOperation } from './deconz.classes.client.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import { captureDeconzOptions, deconzData, normalizeDeconzConfig } from './deconz.validation.js';
 import { DeconzConfigFlow } from './deconz.classes.configflow.js';
 import { createDeconzDiscoveryDescriptor } from './deconz.discovery.js';
 import { DeconzMapper } from './deconz.mapper.js';
-import type { IDeconzConfig, IDeconzGroupActionPatch, IDeconzLightStatePatch, IDeconzSensorConfigPatch, IDeconzSensorStatePatch, IDeconzSnapshot } from './deconz.types.js';
+import type { IDeconzConfig, IDeconzGroupActionPatch, IDeconzIntegrationOptions, IDeconzLightStatePatch, IDeconzSensorConfigPatch, IDeconzSensorStatePatch, IDeconzSnapshot } from './deconz.types.js';
 
 interface IDeconzServiceTarget {
   entity: IIntegrationEntity;
@@ -17,13 +19,13 @@ interface IDeconzServiceTarget {
 }
 
 export class DeconzIntegration extends BaseIntegration<IDeconzConfig> {
-  private readonly clients = new Set<DeconzClient>();
-  private destroyed = false;
+  readonly #owner: NativeIntegrationOwner;
+  readonly #options: Readonly<IDeconzIntegrationOptions>;
   public readonly domain = 'deconz';
   public readonly displayName = 'deCONZ';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createDeconzDiscoveryDescriptor();
-  public readonly configFlow = new DeconzConfigFlow();
+  public readonly configFlow: DeconzConfigFlow;
   public readonly metadata = {
     source: 'home-assistant/core',
     upstreamPath: 'homeassistant/components/deconz',
@@ -36,46 +38,80 @@ export class DeconzIntegration extends BaseIntegration<IDeconzConfig> {
     restDocumentation: 'https://dresden-elektronik.github.io/deconz-rest-doc/',
   };
 
-  public async setup(configArg: IDeconzConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    if (this.destroyed) throw new Error('deCONZ integration has been destroyed.');
-    const client = new DeconzClient(configArg, contextArg.abortSignal);
-    this.clients.add(client);
-    try {
-      await client.getSnapshot(contextArg.abortSignal);
-      if (this.destroyed || !client.isHealthy) throw new Error('deCONZ setup cancelled.');
-      const runtime = new DeconzRuntime(client, () => this.clients.delete(client));
-      return runtime;
-    } catch (error) { await client.destroy(); this.clients.delete(client); throw error; }
+  constructor(optionsArg: IDeconzIntegrationOptions = {}) {
+    super();
+    this.#options = captureDeconzOptions(optionsArg);
+    this.#owner = new NativeIntegrationOwner('deconz', { homeId: this.#options.homeId, capacity: this.#options.capacity });
+    this.configFlow = new DeconzConfigFlow(this.#options, this.#owner);
   }
 
-  public async destroy(): Promise<void> {
-    this.destroyed = true;
-    const results = await Promise.allSettled([...this.clients].map(async (clientArg) => { await clientArg.destroy(); this.clients.delete(clientArg); }));
-    const failures = results.filter((resultArg): resultArg is PromiseRejectedResult => resultArg.status === 'rejected');
-    if (failures.length) throw new AggregateError(failures.map((failureArg) => failureArg.reason), 'deCONZ runtime cleanup failed.');
+  public async setup(configArg: IDeconzConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    const config = normalizeDeconzConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (lease) => {
+      const client = new DeconzClient(config, lease.context, this.#options, this.#owner);
+      let cleanupStarted = false;
+      lease.own(() => { if (cleanupStarted) return client.retryCleanup(); cleanupStarted = true; return client.destroy(); });
+      await client.getSnapshot(lease.signal);
+      lease.assertOpen();
+      if (!client.isHealthy) throw new Error('deCONZ setup cancelled.');
+      lease.promoteToRuntime();
+      return new DeconzRuntime(client, lease);
+    });
   }
+
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
+
 }
 
 export class HomeAssistantDeconzIntegration extends DeconzIntegration {}
 
 class DeconzRuntime implements IIntegrationRuntime {
-  public domain = 'deconz';
-
-  constructor(private readonly client: DeconzClient, private readonly onDestroyed: () => void) {}
-
+  public readonly domain = 'deconz';
+  constructor(private readonly client: DeconzClient, private readonly lease: INativeSetupLease) {}
   public isHealthy(): boolean { return this.client.isHealthy; }
-
-  public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
-    return DeconzMapper.toDevices(await this.client.getSnapshot(abortSignalArg));
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> { return DeconzMapper.toDevices(await this.client.getSnapshot(signalArg)); }
+  public async entities(): Promise<IIntegrationEntity[]> { return DeconzMapper.toEntities(await this.client.getSnapshot()); }
+  public async subscribe(handlerArg: Parameters<NonNullable<IIntegrationRuntime['subscribe']>>[0], signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    return this.client.subscribeToEvents((eventArg) => handlerArg(DeconzMapper.toIntegrationEvent(eventArg)), signalArg, (errorArg) => handlerArg({ type: 'error', integrationDomain: 'deconz', data: { message: errorArg.message }, timestamp: Date.now() }));
   }
-
-  public async entities(): Promise<IIntegrationEntity[]> {
-    return DeconzMapper.toEntities(await this.client.getSnapshot());
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const request = deconzData(requestArg, ['device', 'feature', 'value']);
+      const device = deconzData(request.device, ['id', 'integrationDomain', 'name', 'room', 'protocol', 'manufacturer', 'model', 'online', 'features', 'state', 'metadata']);
+      const feature = deconzData(request.feature, ['id', 'capability', 'name', 'readable', 'writable', 'unit']);
+      if (typeof device.id !== 'string' || typeof device.integrationDomain !== 'string' || typeof feature.id !== 'string' || typeof feature.capability !== 'string' || !['boolean', 'number', 'string'].includes(typeof request.value)) throw new Error('Invalid deCONZ feature request.');
+      const captured = { device: { id: device.id, integrationDomain: device.integrationDomain }, feature: { id: feature.id, capability: feature.capability }, value: request.value } as IDeviceFeatureWriteRequest;
+      const result = await this.client.execute((session) => new DeconzRuntimeCommands(session).writeFeature(captured, signalArg), signalArg);
+      return { ...result.result, ...(result.observation ? { data: result.observation } : {}) };
+    } catch (error) { return this.failure(error); }
   }
-
-  public async subscribe(handlerArg: Parameters<NonNullable<IIntegrationRuntime['subscribe']>>[0], abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
-    return this.client.subscribeToEvents((eventArg) => handlerArg(DeconzMapper.toIntegrationEvent(eventArg)), abortSignalArg, (errorArg) => handlerArg({ type: 'error', integrationDomain: 'deconz', data: { message: errorArg.message }, timestamp: Date.now() }));
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    try {
+      const request = deconzData(requestArg, ['domain', 'service', 'target', 'data']);
+      if (typeof request.domain !== 'string' || typeof request.service !== 'string') throw new Error('Invalid deCONZ service request.');
+      const target = deconzData(request.target, ['entityId', 'deviceId']);
+      if (Object.values(target).some((value) => typeof value !== 'string' || !value)) throw new Error('Invalid deCONZ service target.');
+      const fields = request.domain === 'light' ? request.service === 'turn_on' ? ['brightness', 'brightness_pct', 'percentage', 'transition', 'color_temp', 'color_temp_mired', 'xy_color'] : request.service === 'set_percentage' ? ['percentage'] : [] : request.domain === 'cover' ? ['position', 'percentage'] : ['sensor', 'binary_sensor', 'climate'].includes(request.domain) ? ['field', 'attribute', 'value', 'temperature', 'target_temperature'] : [];
+      const data = request.data === undefined ? undefined : deconzData(request.data, fields);
+      if (data) for (const [key, value] of Object.entries(data)) {
+        if (key === 'xy_color') {
+          if (!Array.isArray(value) || value.length !== 2 || Reflect.ownKeys(value).some((entry) => !['0', '1', 'length'].includes(String(entry)))) throw new Error('Invalid deCONZ color request.');
+          data[key] = ['0', '1'].map((entry) => { const descriptor = Object.getOwnPropertyDescriptor(value, entry); if (!descriptor || !('value' in descriptor) || typeof descriptor.value !== 'number') throw new Error('Invalid deCONZ color request.'); return descriptor.value as number; });
+        } else if (!['string', 'number', 'boolean'].includes(typeof value)) throw new Error('Invalid deCONZ service data.');
+      }
+      const captured = { domain: request.domain, service: request.service, target, data } as IServiceCallRequest;
+      const result = await this.client.execute((session) => new DeconzRuntimeCommands(session).callService(captured));
+      return { ...result.result, ...(result.observation ? { data: result.observation } : {}) };
+    } catch (error) { return this.failure(error); }
   }
+  public destroy(): Promise<void> { return this.lease.close(); }
+  private failure(errorArg: unknown): IServiceCallResult { return { success: false, error: 'deCONZ command failed.', data: { effectOutcome: errorArg instanceof DeconzWriteError ? 'indeterminate' : 'not-sent', causalityConfirmed: false, physicalCompletion: 'unconfirmed' } }; }
+}
+
+class DeconzRuntimeCommands {
+  public readonly domain = 'deconz';
+  constructor(private readonly client: IDeconzClientOperation) {}
 
   public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
     if (!this.client.isHealthy) return { success: false, error: 'deCONZ runtime is not healthy.' };
@@ -140,10 +176,6 @@ class DeconzRuntime implements IIntegrationRuntime {
     return { success: false, error: `Unsupported deCONZ service domain: ${requestArg.domain}` };
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
-    this.onDestroyed();
-  }
 
   private async callLightService(targetArg: IDeconzServiceTarget, requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
     if (targetArg.resource !== 'lights' && targetArg.resource !== 'groups') {

package/ts/integrations/deconz/deconz.mapper.ts

@@ -99,6 +99,11 @@ export class DeconzMapper {
       devices.push(this.sensorToDevice(sensorId, sensor, updatedAt));
     }
 
+    if (snapshotArg.homeId) for (const device of devices) {
+      const resource = typeof device.metadata?.deconzResource === 'string' ? device.metadata.deconzResource : 'gateway';
+      const id = typeof device.metadata?.deconzId === 'string' ? device.metadata.deconzId : bridgeId;
+      device.id = this.canonicalDeviceId(snapshotArg, resource, id);
+    }
     if (snapshotArg.config?.rfconnected === false) {
       return devices.map((deviceArg) => ({ ...deviceArg, online: false, state: deviceArg.state.map((stateArg) => stateArg.featureId === 'connectivity' ? { ...stateArg, value: 'offline' } : stateArg) }));
     }
@@ -138,9 +143,21 @@ export class DeconzMapper {
       }
     }
 
+    if (snapshotArg.homeId) for (const entity of entities) {
+      const resource = String(entity.attributes?.deconzResource);
+      const id = String(entity.attributes?.deconzId);
+      entity.deviceId = this.canonicalDeviceId(snapshotArg, resource, id);
+      const field = entity.attributes?.deconzStateKey ?? entity.attributes?.deconzConfigKey ?? entity.platform;
+      entity.id = entity.uniqueId = `${entity.deviceId}:${entity.platform}:${encodeURIComponent(String(field))}`;
+    }
     return snapshotArg.config?.rfconnected === false ? entities.map((entityArg) => ({ ...entityArg, available: false })) : entities;
   }
 
+  private static canonicalDeviceId(snapshotArg: IDeconzSnapshot, resourceArg: string, idArg: string): string {
+    const item = resourceArg === 'lights' ? snapshotArg.lights[idArg] : resourceArg === 'sensors' ? snapshotArg.sensors[idArg] : undefined;
+    return ['deconz', snapshotArg.homeId!, this.bridgeId(snapshotArg).toLowerCase(), resourceArg, idArg, item?.uniqueid ?? ''].map((partArg) => encodeURIComponent(partArg)).join(':');
+  }
+
   public static toIntegrationEvent(eventArg: IDeconzWebsocketEvent): IIntegrationEvent {
     return {
       type: eventArg.e === 'added' ? 'device_added' : eventArg.e === 'deleted' ? 'device_removed' : 'state_changed',
@@ -185,13 +202,13 @@ export class DeconzMapper {
     ];
 
     if (this.isCoverLight(lightArg)) {
-      features.push({ id: 'position', capability: 'cover', name: 'Position', readable: true, writable: true, unit: '%' });
+      features.push({ id: 'position', capability: 'cover', name: 'Position', readable: true, writable: typeof lightArg.state?.lift === 'number', unit: '%' });
       this.pushDeviceState(state, 'position', this.coverPosition(lightArg), updatedAtArg);
     } else if (this.isSwitchLight(lightArg)) {
-      features.push({ id: 'on', capability: 'switch', name: 'Power', readable: true, writable: true });
+      features.push({ id: 'on', capability: 'switch', name: 'Power', readable: true, writable: typeof lightArg.state?.on === 'boolean' });
       this.pushDeviceState(state, 'on', lightArg.state?.on ?? false, updatedAtArg);
     } else {
-      features.push({ id: 'on', capability: 'light', name: 'Power', readable: true, writable: true });
+      features.push({ id: 'on', capability: 'light', name: 'Power', readable: true, writable: typeof lightArg.state?.on === 'boolean' });
       this.pushDeviceState(state, 'on', lightArg.state?.on ?? false, updatedAtArg);
       if (typeof lightArg.state?.bri === 'number') {
         features.push({ id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: true, unit: '%' });
@@ -238,8 +255,8 @@ export class DeconzMapper {
       online: true,
       features: [
         { id: 'connectivity', capability: 'sensor', name: 'Connectivity', readable: true, writable: false },
-        { id: 'on', capability: 'light', name: 'Power', readable: true, writable: true },
-        { id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: true, unit: '%' },
+        { id: 'on', capability: 'light', name: 'Power', readable: true, writable: typeof groupArg.action?.on === 'boolean' },
+        ...(typeof groupArg.action?.bri === 'number' ? [{ id: 'brightness', capability: 'light' as const, name: 'Brightness', readable: true, writable: true, unit: '%' }] : []),
       ],
       state,
       metadata: {

package/ts/integrations/deconz/deconz.types.ts

@@ -1,3 +1,6 @@
+import type * as plugins from '../../plugins.js';
+import type { IConfigEncryptionKeyProvider } from '../../core/classes.configstore.js';
+
 export type TDeconzProtocol = 'http' | 'https';
 
 export type TDeconzResource = 'config' | 'groups' | 'lights' | 'scenes' | 'sensors';
@@ -9,15 +12,52 @@ export type TDeconzCommandMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
 export type TDeconzStateValue = string | number | boolean | null | undefined | number[] | string[] | Record<string, unknown>;
 
 export interface IDeconzConfig {
-  host?: string;
+  homeId: string;
+  host: string;
   port?: number;
-  apiKey?: string;
+  credentialReference: string;
   protocol?: TDeconzProtocol;
-  bridgeId?: string;
-  websocketPort?: number;
+  bridgeId: string;
   enableWebSocket?: boolean;
   requestTimeoutMs?: number;
-  snapshot?: IDeconzSnapshot;
+}
+
+export interface IDeconzCredentialRequest {
+  readonly homeId: string;
+  readonly origin: string;
+  readonly bridgeId: string;
+  readonly credentialReference: string;
+  readonly signal: AbortSignal;
+  /** Monotonic performance.now() deadline, shared by credential resolution and HTTP dispatch. */
+  readonly deadline: number;
+}
+
+export interface IDeconzCredentialProvider {
+  resolve(requestArg: IDeconzCredentialRequest): Promise<string>;
+  /** Create a reference without replacing an existing credential; the host owns this persistence contract. */
+  create?(requestArg: IDeconzCredentialRequest, apiKeyArg: string): Promise<void>;
+}
+
+export interface IDeconzControlPermission {
+  readonly resource: 'config' | 'lights' | 'groups' | 'sensors' | 'scenes';
+  readonly resourceId: string;
+  readonly fields: readonly string[];
+}
+
+export interface IDeconzIntegrationOptions {
+  readonly homeId?: string;
+  readonly capacity?: number;
+  readonly credentialProvider?: IDeconzCredentialProvider;
+  readonly controlPermissions?: readonly IDeconzControlPermission[];
+  readonly db?: plugins.nosqldb.SmartdataDb;
+  readonly keyProvider?: IConfigEncryptionKeyProvider;
+}
+
+export interface IDeconzWriteResult {
+  readonly effectOutcome: 'accepted';
+  readonly observedState: IDeconzSnapshot;
+  readonly causalityConfirmed: false;
+  readonly physicalCompletion: 'unconfirmed';
 }
 
 export interface IDeconzGatewayConfig {
@@ -58,11 +98,13 @@ export interface IDeconzLightState {
 
 export interface IDeconzLight {
   id?: string;
-  colorcapabilities?: number;
+  colorcapabilities?: number | string[];
+  modes?: string[];
   ctmax?: number;
   ctmin?: number;
   etag?: string;
   hascolor?: boolean;
+  effects?: string[];
   lastannounced?: string;
   lastseen?: string;
   manufacturername?: string;
@@ -192,6 +234,7 @@ export interface IDeconzScene {
 }
 
 export interface IDeconzSnapshot {
+  homeId?: string;
   config?: IDeconzGatewayConfig;
   groups: Record<string, IDeconzGroup>;
   lights: Record<string, IDeconzLight>;