@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/nanoleaf/nanoleaf.classes.integration.ts

@@ -1,227 +1,176 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { NanoleafClient } from './nanoleaf.classes.client.js';
 import { NanoleafConfigFlow } from './nanoleaf.classes.configflow.js';
 import { createNanoleafDiscoveryDescriptor } from './nanoleaf.discovery.js';
 import { NanoleafMapper } from './nanoleaf.mapper.js';
-import type { INanoleafConfig } from './nanoleaf.types.js';
+import type { INanoleafConfig, INanoleafIntegrationOptions, INanoleafSnapshot, INanoleafWriteResult } from './nanoleaf.types.js';
+import { nanoleafInteger, nanoleafKeys, nanoleafRecord, nanoleafText, normalizeNanoleafConfig } from './nanoleaf.validation.js';
 
 export class NanoleafIntegration extends BaseIntegration<INanoleafConfig> {
   public readonly domain = 'nanoleaf';
   public readonly displayName = 'Nanoleaf';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createNanoleafDiscoveryDescriptor();
-  public readonly configFlow = new NanoleafConfigFlow();
+  public readonly configFlow: NanoleafConfigFlow;
   public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/nanoleaf',
-    upstreamDomain: 'nanoleaf',
-    integrationType: 'device',
-    iotClass: 'local_push',
-    documentation: 'https://www.home-assistant.io/integrations/nanoleaf',
-    requirements: ['aionanoleaf2==1.0.2'],
-    codeowners: ['@milanmeu', '@joostlek', '@loebi-ch', '@JaspervRijbroek', '@jonathanrobichaud4'],
-    zeroconf: ['_nanoleafms._tcp.local.', '_nanoleafapi._tcp.local.'],
-    ssdp: ['Nanoleaf_aurora:light', 'nanoleaf:nl29', 'nanoleaf:nl42', 'nanoleaf:nl52', 'nanoleaf:nl69', 'inanoleaf:nl81'],
-    homekitModels: ['NL29', 'NL42', 'NL47', 'NL48', 'NL52', 'NL59', 'NL69', 'NL81'],
+    source: 'home-assistant/core', upstreamDomain: 'nanoleaf', integrationType: 'device', iotClass: 'local_poll',
+    localApi: { implemented: ['selected verified aggregate controller', 'encrypted home-scoped existing token', 'fresh observed capability/state',
+      'absolute power/brightness/Kelvin', 'current advertised scene selection', 'single submission and terminal drain'],
+    explicitUnsupported: ['pairing/token revocation', 'discovery identity trust', 'injected snapshots or clients', 'RGB conversion', 'hue/saturation controls',
+      'panel/rhythm entities', 'identify', 'animations/streaming', 'increment/toggle/transitions', 'subscriptions', 'automatic retries', 'physical completion claims'] },
   };
+  readonly #owner: NativeIntegrationOwner;
+  readonly #credentials?: INanoleafIntegrationOptions;
+
+  constructor(ownerArg?: INanoleafIntegrationOptions) {
+    super();
+    this.#owner = new NativeIntegrationOwner(this.domain, { homeId: ownerArg?.homeId });
+    this.#credentials = ownerArg && Object.freeze({ db: ownerArg.db, keyProvider: ownerArg.keyProvider });
+    this.configFlow = new NanoleafConfigFlow(this.#credentials, this.#owner.createFlowScope());
+  }
+
+  public setup(configArg: INanoleafConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    try {
+      const config = normalizeNanoleafConfig(configArg);
+      return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+        const client = new NanoleafClient(config, leaseArg.context.configStore ?? this.#credentials, undefined, leaseArg.context.homeId);
+        let firstCleanup = true;
+        leaseArg.own(() => {
+          if (!firstCleanup) return client.retryCleanup();
+          firstCleanup = false;
+          return client.destroy();
+        });
+        const identity = await client.getSnapshot(leaseArg.signal);
+        leaseArg.assertOpen();
+        const runtime = new NanoleafRuntime(client, identity, leaseArg);
+        leaseArg.promoteToRuntime();
+        return runtime;
+      });
+    } catch (errorArg) { return Promise.reject(errorArg); }
+  }
 
-  public async setup(configArg: INanoleafConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new NanoleafRuntime(new NanoleafClient(configArg));
+  public destroy(): Promise<void> {
+    return this.#owner.close();
   }
 
-  public async destroy(): Promise<void> {}
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantNanoleafIntegration extends NanoleafIntegration {}
 
 class NanoleafRuntime implements IIntegrationRuntime {
-  public domain = 'nanoleaf';
-
-  constructor(private readonly client: NanoleafClient) {}
-
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return NanoleafMapper.toDevices(await this.client.getSnapshot());
+  public readonly domain = 'nanoleaf';
+  readonly #deviceId: string;
+  readonly #lightId: string;
+  readonly #effectId: string;
+  #closePromise?: Promise<void>;
+  #removeParentAbort: () => void = () => undefined;
+
+  constructor(private readonly client: NanoleafClient, identityArg: INanoleafSnapshot, private readonly lease: INativeSetupLease) {
+    this.#deviceId = NanoleafMapper.deviceId(identityArg);
+    this.#lightId = NanoleafMapper.lightEntityId(identityArg);
+    this.#effectId = NanoleafMapper.effectEntityId(identityArg);
+    const aborted = (): void => { void this.destroy().catch(() => undefined); };
+    lease.signal.addEventListener('abort', aborted, { once: true });
+    this.#removeParentAbort = () => lease.signal.removeEventListener('abort', aborted);
+    if (lease.signal.aborted) aborted();
   }
 
+  public isHealthy(): boolean { return !this.#closePromise && this.client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.#assertOpen();
+    return NanoleafMapper.toDevices(await this.client.getSnapshot(signalArg ? AbortSignal.any([this.lease.signal, signalArg]) : this.lease.signal));
+  }
   public async entities(): Promise<IIntegrationEntity[]> {
-    return NanoleafMapper.toEntities(await this.client.getSnapshot());
+    this.#assertOpen();
+    return NanoleafMapper.toEntities(await this.client.getSnapshot(this.lease.signal));
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
     try {
-      if (requestArg.domain === 'nanoleaf' && requestArg.service === 'create_auth_token') {
-        const result = await this.client.createAuthToken();
-        return { success: result.success, error: result.error, data: result };
-      }
-
-      if (requestArg.domain === 'button') {
-        if (requestArg.service === 'press') {
-          await this.client.identify();
-          return { success: true };
-        }
-        return { success: false, error: `Unsupported Nanoleaf button service: ${requestArg.service}` };
-      }
-
-      if (requestArg.domain === 'select') {
-        return this.handleSelectEffect(requestArg);
-      }
-
-      if (requestArg.domain === 'number') {
-        return this.handleNumberService(requestArg);
-      }
-
-      if (requestArg.domain !== 'light') {
-        return { success: false, error: `Unsupported Nanoleaf service domain: ${requestArg.domain}` };
-      }
-
-      if (requestArg.service === 'turn_on') {
-        return this.handleTurnOn(requestArg);
+      this.#assertOpen();
+      const request = nanoleafRecord(requestArg, 'service request');
+      nanoleafKeys(request, ['domain', 'service', 'target', 'data']);
+      const data = request.data === undefined ? {} : nanoleafRecord(request.data, 'service data');
+      if (request.domain === 'nanoleaf' && request.service === 'snapshot') {
+        this.#assertTarget(request.target);
+        nanoleafKeys(data, []);
+        return { success: true, data: await this.client.getSnapshot(this.lease.signal) };
       }
-      if (requestArg.service === 'turn_off') {
-        await this.client.turnOff(this.numberValue(requestArg.data, 'transition'));
-        return { success: true };
+      if (request.domain === 'select' && request.service === 'select_option') {
+        this.#assertTarget(request.target, this.#effectId);
+        nanoleafKeys(data, ['option']);
+        return accepted(await this.client.selectEffect(nanoleafText(data.option, 'advertised scene'), this.lease.signal));
       }
-      if (requestArg.service === 'set_value') {
-        return this.handleSetValue(requestArg);
+      this.#assertTarget(request.target, this.#lightId);
+      if (request.domain !== 'light') throw new TypeError('Nanoleaf service is unsupported.');
+      if (request.service === 'turn_on' || request.service === 'turn_off') {
+        nanoleafKeys(data, []);
+        return accepted(await this.client.setPower(request.service === 'turn_on', this.lease.signal));
       }
-      if (requestArg.service === 'set_percentage' || requestArg.service === 'set_brightness') {
-        return this.handleSetBrightness(requestArg);
+      if (request.service === 'set_brightness') {
+        nanoleafKeys(data, ['brightness']);
+        return accepted(await this.client.setBrightness(nanoleafInteger(data.brightness, 0, 100, 'brightness'), this.lease.signal));
       }
-      if (requestArg.service === 'select_effect') {
-        return this.handleSelectEffect(requestArg);
+      if (request.service === 'set_color_temperature') {
+        nanoleafKeys(data, ['kelvin']);
+        return accepted(await this.client.setColorTemperature(nanoleafInteger(data.kelvin, 1, 100000, 'kelvin'), this.lease.signal));
       }
-
-      return { success: false, error: `Unsupported Nanoleaf light service: ${requestArg.service}` };
-    } catch (error) {
-      return { success: false, error: error instanceof Error ? error.message : String(error) };
-    }
-  }
-
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
-  }
-
-  private async handleTurnOn(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const effect = this.stringValue(requestArg.data, 'effect', 'option');
-    if (effect) {
-      await this.client.setEffect(effect);
-    }
-
-    const hsColor = requestArg.data?.hs_color;
-    if (Array.isArray(hsColor) && typeof hsColor[0] === 'number' && typeof hsColor[1] === 'number') {
-      await this.client.setHue(hsColor[0]);
-      await this.client.setSaturation(hsColor[1]);
-    }
-
-    const colorTemperature = this.numberValue(requestArg.data, 'color_temp_kelvin', 'kelvin', 'ct');
-    if (colorTemperature !== undefined) {
-      await this.client.setColorTemperature(colorTemperature);
-    }
-
-    await this.client.turnOn();
-
-    const brightness = this.brightnessPercent(requestArg.data);
-    if (brightness !== undefined) {
-      await this.client.setBrightness(brightness, this.numberValue(requestArg.data, 'transition'));
-    }
-
-    return { success: true };
-  }
-
-  private async handleNumberService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.service !== 'set_value' && requestArg.service !== 'set_percentage' && requestArg.service !== 'set_brightness') {
-      return { success: false, error: `Unsupported Nanoleaf number service: ${requestArg.service}` };
-    }
-    return requestArg.service === 'set_value' ? this.handleSetValue(requestArg) : this.handleSetBrightness(requestArg);
-  }
-
-  private async handleSetValue(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const value = this.numberValue(requestArg.data, 'value', 'brightness', 'percentage');
-    if (value === undefined) {
-      return { success: false, error: 'Nanoleaf set_value requires data.value.' };
-    }
-
-    const target = `${requestArg.target.entityId ?? ''} ${this.stringValue(requestArg.data, 'attribute', 'feature') ?? ''}`.toLowerCase();
-    if (target.includes('hue')) {
-      await this.client.setHue(value);
-      return { success: true };
-    }
-    if (target.includes('saturation') || target.includes('sat')) {
-      await this.client.setSaturation(value);
-      return { success: true };
-    }
-    if (target.includes('temperature') || target.includes('color_temp') || target.includes('ct')) {
-      await this.client.setColorTemperature(value);
-      return { success: true };
-    }
-
-    await this.client.setBrightness(this.brightnessPercent(requestArg.data) ?? value, this.numberValue(requestArg.data, 'transition'));
-    return { success: true };
-  }
-
-  private async handleSetBrightness(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const brightness = this.brightnessPercent(requestArg.data);
-    if (brightness === undefined) {
-      return { success: false, error: 'Nanoleaf brightness service requires data.percentage, data.brightness, or data.value.' };
-    }
-    await this.client.setBrightness(brightness, this.numberValue(requestArg.data, 'transition'));
-    return { success: true };
+      throw new TypeError('Nanoleaf service is unsupported.');
+    } catch (errorArg) { return failed(errorArg); }
   }
 
-  private async handleSelectEffect(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const effect = this.stringValue(requestArg.data, 'effect', 'option', 'value');
-    if (!effect) {
-      return { success: false, error: 'Nanoleaf select_effect requires data.effect or data.option.' };
-    }
-    await this.client.setEffect(effect);
-    return { success: true };
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      this.#assertOpen();
+      const signal = signalArg ? AbortSignal.any([this.lease.signal, signalArg]) : this.lease.signal;
+      const request = nanoleafRecord(requestArg, 'feature write');
+      nanoleafKeys(request, ['device', 'feature', 'value']);
+      const device = nanoleafRecord(request.device, 'feature device');
+      const feature = nanoleafRecord(request.feature, 'feature');
+      if (device.id !== this.#deviceId || device.integrationDomain !== this.domain) throw new TypeError('Nanoleaf feature device is not owned by this home runtime.');
+      if (feature.id === 'power') {
+        if (typeof request.value !== 'boolean') throw new TypeError('Nanoleaf power requires an exact boolean.');
+        return accepted(await this.client.setPower(request.value, signal));
+      }
+      if (feature.id === 'brightness') return accepted(await this.client.setBrightness(nanoleafInteger(request.value, 0, 100, 'brightness'), signal));
+      if (feature.id === 'color_temperature') return accepted(await this.client.setColorTemperature(nanoleafInteger(request.value, 1, 100000, 'kelvin'), signal));
+      if (feature.id === 'effect') return accepted(await this.client.selectEffect(nanoleafText(request.value, 'advertised scene'), signal));
+      throw new TypeError('Nanoleaf feature is not writable.');
+    } catch (errorArg) { return failed(errorArg); }
   }
 
-  private brightnessPercent(dataArg: Record<string, unknown> | undefined): number | undefined {
-    const percentage = this.numberValue(dataArg, 'brightness_pct', 'percentage', 'percent', 'value');
-    if (percentage !== undefined) {
-      return this.clamp(Math.round(percentage), 0, 100);
-    }
-    const brightness = this.numberValue(dataArg, 'brightness');
-    if (brightness === undefined) {
-      return undefined;
-    }
-    return this.clamp(Math.round(brightness > 100 ? brightness / 2.55 : brightness), 0, 100);
+  public destroy(): Promise<void> {
+    if (this.#closePromise) return this.#closePromise;
+    this.#closePromise = Promise.resolve().then(() => this.lease.close());
+    this.#removeParentAbort();
+    return this.#closePromise;
   }
 
-  private numberValue(dataArg: Record<string, unknown> | undefined, ...keysArg: string[]): number | undefined {
-    if (!dataArg) {
-      return undefined;
-    }
-    for (const key of keysArg) {
-      const value = dataArg[key];
-      if (typeof value === 'number' && Number.isFinite(value)) {
-        return value;
-      }
-      if (typeof value === 'string' && value.trim() && Number.isFinite(Number(value))) {
-        return Number(value);
-      }
-    }
-    return undefined;
+  #assertOpen(): void {
+    if (this.#closePromise || this.lease.signal.aborted) throw new plugins.ecobridgeDeviceManager.NanoleafProtocolError('CLOSED', 'Nanoleaf runtime is destroyed.');
   }
 
-  private stringValue(dataArg: Record<string, unknown> | undefined, ...keysArg: string[]): string | undefined {
-    if (!dataArg) {
-      return undefined;
+  #assertTarget(valueArg: unknown, entityArg?: string): void {
+    const target = nanoleafRecord(valueArg, 'service target');
+    nanoleafKeys(target, ['deviceId', 'entityId']);
+    if (target.deviceId === undefined && target.entityId === undefined ||
+      target.deviceId !== undefined && target.deviceId !== this.#deviceId ||
+      target.entityId !== undefined && target.entityId !== (entityArg ?? this.#lightId) && target.entityId !== (entityArg ?? this.#effectId)) {
+      throw new TypeError('Nanoleaf service requires one exact owned controller or corresponding entity target.');
     }
-    for (const key of keysArg) {
-      const value = dataArg[key];
-      if (typeof value === 'string' && value) {
-        return value;
-      }
-    }
-    return undefined;
   }
+}
 
-  private clamp(valueArg: number, minArg: number, maxArg: number): number {
-    return Math.max(minArg, Math.min(maxArg, valueArg));
+function accepted(resultArg: INanoleafWriteResult): IServiceCallResult {
+  return { success: true, data: { effectOutcome: 'accepted', observedState: resultArg.snapshot, physicalCompletion: 'unconfirmed' } };
+}
+function failed(errorArg: unknown): IServiceCallResult {
+  if (errorArg instanceof plugins.ecobridgeDeviceManager.NanoleafProtocolError) {
+    return { success: false, error: errorArg.message, data: { code: errorArg.code, effectOutcome: errorArg.effectOutcome } };
   }
+  return { success: false, error: 'Nanoleaf operation was not sent because it was invalid, cancelled or closed.', data: { effectOutcome: 'not-sent' } };
 }

package/ts/integrations/nanoleaf/nanoleaf.credentials.ts

@@ -0,0 +1,39 @@
+import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import type { INanoleafConfig, INanoleafCredential, INanoleafIntegrationOptions } from './nanoleaf.types.js';
+import { nanoleafKeys, nanoleafRecord, nanoleafText } from './nanoleaf.validation.js';
+
+export function createNanoleafCredentialStore(configArg: INanoleafConfig, homeIdArg: string, ownerArg?: INanoleafIntegrationOptions | NoSqlConfigStore): {
+  store: NoSqlConfigStore; owned: boolean;
+} {
+  const homeId = nanoleafText(homeIdArg, 'admitted host home');
+  if (configArg.homeId !== homeId) throw new TypeError('Nanoleaf configuration must match the admitted host home.');
+  if (ownerArg instanceof NoSqlConfigStore) {
+    const scope = NoSqlConfigStore.prototype.getScope.call(ownerArg);
+    if (scope.homeId !== homeId || scope.integrationDomain !== 'nanoleaf') {
+      throw new TypeError('Nanoleaf credential store must match the admitted host home and nanoleaf domain.');
+    }
+    return { store: ownerArg, owned: false };
+  }
+  if (!ownerArg?.db || !ownerArg.keyProvider) throw new TypeError('Nanoleaf requires a caller-owned database and external encryption key provider or encrypted NoSqlConfigStore.');
+  return { store: new NoSqlConfigStore({ db: ownerArg.db, keyProvider: ownerArg.keyProvider,
+    homeId, integrationDomain: 'nanoleaf', timeoutMs: configArg.timeoutMs }), owned: true };
+}
+
+export function nanoleafCredentialKey(configArg: INanoleafConfig): string {
+  return `nanoleaf.credential.${encodeURIComponent(configArg.credentialKey)}`;
+}
+
+export function nanoleafCredential(configArg: INanoleafConfig, tokenArg: unknown): INanoleafCredential {
+  return { version: 1, origin: configArg.origin, serialNumber: configArg.expectedSerialNumber,
+    model: configArg.expectedModel, authToken: nanoleafText(tokenArg, 'existing auth token', 512) };
+}
+
+export function readNanoleafCredential(configArg: INanoleafConfig, valueArg: unknown): string {
+  const credential = nanoleafRecord(valueArg, 'stored credential');
+  nanoleafKeys(credential, ['version', 'origin', 'serialNumber', 'model', 'authToken']);
+  if (credential.version !== 1 || credential.origin !== configArg.origin ||
+    credential.serialNumber !== configArg.expectedSerialNumber || credential.model !== configArg.expectedModel) {
+    throw new TypeError('Nanoleaf encrypted credential does not match this exact controller endpoint and identity.');
+  }
+  return nanoleafText(credential.authToken, 'existing auth token', 512);
+}