@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/nanoleaf/nanoleaf.mapper.ts

@@ -1,274 +1,61 @@
-import * as plugins from '../../plugins.js';
-import type { IIntegrationEntity, IIntegrationEvent } from '../../core/types.js';
-import type {
-  INanoleafEvent,
-  INanoleafPanelInfo,
-  INanoleafSnapshot,
-  INanoleafState,
-  INanoleafValue,
-} from './nanoleaf.types.js';
-
-const RESERVED_EFFECTS = new Set(['*Solid*', '*Static*', '*Dynamic*']);
+import type * as plugins from '../../plugins.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import type { INanoleafSnapshot } from './nanoleaf.types.js';
 
 export class NanoleafMapper {
+  public static deviceId(snapshotArg: Pick<INanoleafSnapshot, 'homeId' | 'serialNumber'>): string {
+    return `nanoleaf:${encodeURIComponent(snapshotArg.homeId)}:${encodeURIComponent(snapshotArg.serialNumber)}`;
+  }
+
+  public static lightEntityId(snapshotArg: Pick<INanoleafSnapshot, 'homeId' | 'serialNumber'>): string { return `${this.deviceId(snapshotArg)}:light`; }
+  public static effectEntityId(snapshotArg: Pick<INanoleafSnapshot, 'homeId' | 'serialNumber'>): string { return `${this.deviceId(snapshotArg)}:effect`; }
+
   public static toDevices(snapshotArg: INanoleafSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
-    const devices: plugins.shxInterfaces.data.IDeviceDefinition[] = [];
-    const updatedAt = new Date().toISOString();
-    const controllerDeviceId = this.controllerDeviceId(snapshotArg);
-    const controllerName = this.controllerName(snapshotArg);
+    const updatedAt = snapshotArg.observedAt;
     const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
-      { 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: 'hue', capability: 'light', name: 'Hue', readable: true, writable: true },
-      { id: 'saturation', capability: 'light', name: 'Saturation', readable: true, writable: true, unit: '%' },
-      { id: 'color_temperature', capability: 'light', name: 'Color temperature', readable: true, writable: true, unit: 'K' },
-      { id: 'color_mode', capability: 'sensor', name: 'Color mode', readable: true, writable: false },
-      { id: 'effect', capability: 'light', name: 'Effect', readable: true, writable: true },
+      { id: 'power', capability: 'light', name: 'Power', readable: true, writable: true },
+      { id: 'firmware', capability: 'sensor', name: 'Firmware', readable: true, writable: false },
     ];
     const state: plugins.shxInterfaces.data.IDeviceState[] = [
-      { featureId: 'connectivity', value: 'online', updatedAt },
-      { featureId: 'on', value: this.stateValue(snapshotArg.state.on) ?? null, updatedAt },
-      { featureId: 'brightness', value: this.stateValue(snapshotArg.state.brightness) ?? null, updatedAt },
-      { featureId: 'hue', value: this.stateValue(snapshotArg.state.hue) ?? null, updatedAt },
-      { featureId: 'saturation', value: this.stateValue(snapshotArg.state.sat) ?? null, updatedAt },
-      { featureId: 'color_temperature', value: this.stateValue(snapshotArg.state.ct) ?? null, updatedAt },
-      { featureId: 'color_mode', value: this.colorMode(snapshotArg.state) ?? null, updatedAt },
-      { featureId: 'effect', value: this.currentEffect(snapshotArg) ?? null, updatedAt },
+      { featureId: 'power', value: snapshotArg.power, updatedAt },
+      { featureId: 'firmware', value: snapshotArg.firmwareVersion, updatedAt },
     ];
-
-    if (snapshotArg.controllerInfo.firmwareVersion) {
-      features.push({ id: 'firmware', capability: 'sensor', name: 'Firmware', readable: true, writable: false });
-      state.push({ featureId: 'firmware', value: snapshotArg.controllerInfo.firmwareVersion, updatedAt });
-    }
-
-    const panelCount = this.panelCount(snapshotArg);
-    if (panelCount !== undefined) {
-      features.push({ id: 'panel_count', capability: 'sensor', name: 'Panel count', readable: true, writable: false });
-      state.push({ featureId: 'panel_count', value: panelCount, updatedAt });
-    }
-
-    const rhythmConnected = this.valueLike(snapshotArg.rhythm?.rhythmConnected);
-    if (rhythmConnected !== undefined) {
-      features.push({ id: 'rhythm_connected', capability: 'sensor', name: 'Rhythm connected', readable: true, writable: false });
-      state.push({ featureId: 'rhythm_connected', value: rhythmConnected, updatedAt });
-    }
-
-    devices.push({
-      id: controllerDeviceId,
-      integrationDomain: 'nanoleaf',
-      name: controllerName,
-      protocol: 'http',
-      manufacturer: snapshotArg.controllerInfo.manufacturer || 'Nanoleaf',
-      model: snapshotArg.controllerInfo.model || 'Nanoleaf Controller',
-      online: true,
-      features,
-      state,
-      metadata: {
-        serialNumber: snapshotArg.controllerInfo.serialNo,
-        hardwareVersion: snapshotArg.controllerInfo.hardwareVersion,
-        firmwareVersion: snapshotArg.controllerInfo.firmwareVersion,
-        effectsList: this.availableEffects(snapshotArg),
-      },
-    });
-
-    for (const panel of this.panels(snapshotArg)) {
-      devices.push(this.panelDevice(snapshotArg, panel, updatedAt));
-    }
-
-    return devices;
+    for (const [id, name, unit, observation] of [
+      ['brightness', 'Brightness', '%', snapshotArg.brightness],
+      ['color_temperature', 'Color temperature', 'K', snapshotArg.colorTemperatureKelvin],
+    ] as const) {
+      if (observation) {
+        features.push({ id, capability: 'light', name, unit, readable: true, writable: true });
+        state.push({ featureId: id, value: observation.value, updatedAt });
+      }
+    }
+    if (snapshotArg.availableEffects.length > 0) features.push({ id: 'effect', capability: 'light', name: 'Advertised scene', readable: snapshotArg.selectedEffect !== undefined,
+      writable: true });
+    if (snapshotArg.selectedEffect !== undefined) state.push({ featureId: 'effect', value: snapshotArg.selectedEffect, updatedAt });
+    if (snapshotArg.colorMode !== undefined) {
+      features.push({ id: 'color_mode', capability: 'sensor', name: 'Color mode', readable: true, writable: false });
+      state.push({ featureId: 'color_mode', value: snapshotArg.colorMode, updatedAt });
+    }
+    return [{ id: this.deviceId(snapshotArg), integrationDomain: 'nanoleaf', name: snapshotArg.name,
+      manufacturer: 'Nanoleaf', model: snapshotArg.model, protocol: 'http', online: true, features, state,
+      metadata: { homeId: snapshotArg.homeId, serialNumber: snapshotArg.serialNumber, origin: snapshotArg.origin,
+        observedAt: snapshotArg.observedAt, brightnessRange: snapshotArg.brightness && [snapshotArg.brightness.min, snapshotArg.brightness.max],
+        colorTemperatureRange: snapshotArg.colorTemperatureKelvin && [snapshotArg.colorTemperatureKelvin.min, snapshotArg.colorTemperatureKelvin.max],
+        availableEffects: [...snapshotArg.availableEffects], transportEncrypted: snapshotArg.origin.startsWith('https:'), physicalCompletion: 'unconfirmed' } }];
   }
 
   public static toEntities(snapshotArg: INanoleafSnapshot): IIntegrationEntity[] {
-    const deviceId = this.controllerDeviceId(snapshotArg);
-    const deviceSlug = this.slug(this.controllerName(snapshotArg));
-    const entities: IIntegrationEntity[] = [
-      {
-        id: `light.${deviceSlug}`,
-        uniqueId: `nanoleaf_${this.slug(snapshotArg.controllerInfo.serialNo || deviceId)}_light`,
-        integrationDomain: 'nanoleaf',
-        deviceId,
-        platform: 'light',
-        name: this.controllerName(snapshotArg),
-        state: this.stateValue(snapshotArg.state.on) ? 'on' : 'off',
-        attributes: {
-          brightness: this.stateValue(snapshotArg.state.brightness),
-          hue: this.stateValue(snapshotArg.state.hue),
-          saturation: this.stateValue(snapshotArg.state.sat),
-          color_temp_kelvin: this.stateValue(snapshotArg.state.ct),
-          color_mode: this.colorMode(snapshotArg.state),
-          effect: this.currentEffect(snapshotArg),
-          effect_list: this.availableEffects(snapshotArg),
-        },
-        available: true,
-      },
-      {
-        id: `button.${deviceSlug}_identify`,
-        uniqueId: `nanoleaf_${this.slug(snapshotArg.controllerInfo.serialNo || deviceId)}_identify`,
-        integrationDomain: 'nanoleaf',
-        deviceId,
-        platform: 'button',
-        name: `${this.controllerName(snapshotArg)} identify`,
-        state: null,
-        attributes: { deviceClass: 'identify' },
-        available: true,
-      },
-    ];
-
-    entities.push({
-      id: `select.${deviceSlug}_effect`,
-      uniqueId: `nanoleaf_${this.slug(snapshotArg.controllerInfo.serialNo || deviceId)}_effect`,
-      integrationDomain: 'nanoleaf',
-      deviceId,
-      platform: 'select',
-      name: `${this.controllerName(snapshotArg)} effect`,
-      state: this.currentEffect(snapshotArg) ?? null,
-      attributes: { options: this.availableEffects(snapshotArg) },
-      available: true,
-    });
-
-    this.pushSensorEntity(entities, deviceId, `nanoleaf_${this.slug(deviceId)}_color_mode`, `sensor.${deviceSlug}_color_mode`, `${this.controllerName(snapshotArg)} color mode`, this.colorMode(snapshotArg.state));
-    this.pushSensorEntity(entities, deviceId, `nanoleaf_${this.slug(deviceId)}_firmware`, `sensor.${deviceSlug}_firmware`, `${this.controllerName(snapshotArg)} firmware`, snapshotArg.controllerInfo.firmwareVersion);
-    this.pushSensorEntity(entities, deviceId, `nanoleaf_${this.slug(deviceId)}_panel_count`, `sensor.${deviceSlug}_panel_count`, `${this.controllerName(snapshotArg)} panel count`, this.panelCount(snapshotArg));
-    this.pushSensorEntity(entities, deviceId, `nanoleaf_${this.slug(deviceId)}_rhythm_connected`, `sensor.${deviceSlug}_rhythm_connected`, `${this.controllerName(snapshotArg)} rhythm connected`, this.valueLike(snapshotArg.rhythm?.rhythmConnected));
-    this.pushSensorEntity(entities, deviceId, `nanoleaf_${this.slug(deviceId)}_rhythm_active`, `sensor.${deviceSlug}_rhythm_active`, `${this.controllerName(snapshotArg)} rhythm active`, this.valueLike(snapshotArg.rhythm?.rhythmActive));
-
-    for (const panel of this.panels(snapshotArg)) {
-      const panelDeviceId = this.panelDeviceId(snapshotArg, panel);
-      entities.push({
-        id: `sensor.${deviceSlug}_panel_${panel.panelId}`,
-        uniqueId: `nanoleaf_${this.slug(deviceId)}_panel_${panel.panelId}`,
-        integrationDomain: 'nanoleaf',
-        deviceId: panelDeviceId,
-        platform: 'sensor',
-        name: `${this.controllerName(snapshotArg)} panel ${panel.panelId}`,
-        state: panel.panelId,
-        attributes: {
-          x: panel.x,
-          y: panel.y,
-          orientation: panel.o,
-          shapeType: panel.shapeType,
-        },
-        available: true,
-      });
+    const lightId = this.lightEntityId(snapshotArg);
+    const entities: IIntegrationEntity[] = [{ id: lightId, uniqueId: lightId, deviceId: this.deviceId(snapshotArg), integrationDomain: 'nanoleaf',
+      platform: 'light', name: snapshotArg.name, state: snapshotArg.power ? 'on' : 'off', available: true,
+      attributes: { brightness: snapshotArg.brightness?.value, colorTemperatureKelvin: snapshotArg.colorTemperatureKelvin?.value,
+        colorMode: snapshotArg.colorMode, observedAt: snapshotArg.observedAt } }];
+    if (snapshotArg.availableEffects.length) {
+      const effectId = this.effectEntityId(snapshotArg);
+      entities.push({ id: effectId, uniqueId: effectId, deviceId: this.deviceId(snapshotArg), integrationDomain: 'nanoleaf',
+        platform: 'select', name: `${snapshotArg.name} scene`, state: snapshotArg.selectedEffect ?? null, available: true,
+        attributes: { options: [...snapshotArg.availableEffects], observedAt: snapshotArg.observedAt } });
     }
-
     return entities;
   }
-
-  public static toIntegrationEvent(eventArg: INanoleafEvent): IIntegrationEvent {
-    return {
-      type: 'state_changed',
-      integrationDomain: 'nanoleaf',
-      data: eventArg,
-      timestamp: eventArg.timestamp ?? Date.now(),
-    };
-  }
-
-  private static panelDevice(snapshotArg: INanoleafSnapshot, panelArg: INanoleafPanelInfo, updatedAtArg: string): plugins.shxInterfaces.data.IDeviceDefinition {
-    const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
-      { id: 'layout_x', capability: 'sensor', name: 'Layout X', readable: true, writable: false },
-      { id: 'layout_y', capability: 'sensor', name: 'Layout Y', readable: true, writable: false },
-      { id: 'orientation', capability: 'sensor', name: 'Orientation', readable: true, writable: false },
-      { id: 'shape_type', capability: 'sensor', name: 'Shape type', readable: true, writable: false },
-    ];
-    return {
-      id: this.panelDeviceId(snapshotArg, panelArg),
-      integrationDomain: 'nanoleaf',
-      name: `${this.controllerName(snapshotArg)} Panel ${panelArg.panelId}`,
-      protocol: 'http',
-      manufacturer: 'Nanoleaf',
-      model: panelArg.shapeType === undefined ? 'Panel' : `Panel shape ${panelArg.shapeType}`,
-      online: true,
-      features,
-      state: [
-        { featureId: 'layout_x', value: panelArg.x ?? null, updatedAt: updatedAtArg },
-        { featureId: 'layout_y', value: panelArg.y ?? null, updatedAt: updatedAtArg },
-        { featureId: 'orientation', value: panelArg.o ?? null, updatedAt: updatedAtArg },
-        { featureId: 'shape_type', value: panelArg.shapeType ?? null, updatedAt: updatedAtArg },
-      ],
-      metadata: {
-        panelId: panelArg.panelId,
-        controllerDeviceId: this.controllerDeviceId(snapshotArg),
-      },
-    };
-  }
-
-  private static pushSensorEntity(
-    entitiesArg: IIntegrationEntity[],
-    deviceIdArg: string,
-    uniqueIdArg: string,
-    idArg: string,
-    nameArg: string,
-    valueArg: unknown
-  ): void {
-    if (valueArg === undefined) {
-      return;
-    }
-    entitiesArg.push({
-      id: idArg,
-      uniqueId: uniqueIdArg,
-      integrationDomain: 'nanoleaf',
-      deviceId: deviceIdArg,
-      platform: 'sensor',
-      name: nameArg,
-      state: valueArg,
-      available: true,
-    });
-  }
-
-  private static controllerDeviceId(snapshotArg: INanoleafSnapshot): string {
-    return `nanoleaf.controller.${this.slug(snapshotArg.controllerInfo.serialNo || snapshotArg.controllerInfo.name || 'unknown')}`;
-  }
-
-  private static panelDeviceId(snapshotArg: INanoleafSnapshot, panelArg: INanoleafPanelInfo): string {
-    return `nanoleaf.panel.${this.slug(snapshotArg.controllerInfo.serialNo || snapshotArg.controllerInfo.name || 'unknown')}.${panelArg.panelId}`;
-  }
-
-  private static controllerName(snapshotArg: INanoleafSnapshot): string {
-    return snapshotArg.controllerInfo.name || snapshotArg.controllerInfo.model || 'Nanoleaf';
-  }
-
-  private static panels(snapshotArg: INanoleafSnapshot): INanoleafPanelInfo[] {
-    return snapshotArg.panelLayout?.layout?.positionData ?? [];
-  }
-
-  private static panelCount(snapshotArg: INanoleafSnapshot): number | undefined {
-    return snapshotArg.panelLayout?.layout?.numPanels ?? snapshotArg.panelLayout?.layout?.positionData?.length;
-  }
-
-  private static currentEffect(snapshotArg: INanoleafSnapshot): string | undefined {
-    const effect = snapshotArg.effects.select;
-    if (!effect || RESERVED_EFFECTS.has(effect)) {
-      return undefined;
-    }
-    return effect;
-  }
-
-  private static availableEffects(snapshotArg: INanoleafSnapshot): string[] {
-    return (snapshotArg.effects.effectsList ?? []).filter((effectArg) => !RESERVED_EFFECTS.has(effectArg));
-  }
-
-  private static colorMode(stateArg: INanoleafState): string | undefined {
-    return this.valueLike(stateArg.colorMode);
-  }
-
-  private static stateValue<TValue>(valueArg: INanoleafValue<TValue> | undefined): TValue | undefined {
-    return valueArg?.value;
-  }
-
-  private static valueLike<TValue>(valueArg: INanoleafValue<TValue> | TValue | undefined): TValue | undefined {
-    if (this.isRecord(valueArg) && 'value' in valueArg) {
-      return valueArg.value as TValue;
-    }
-    return valueArg as TValue | undefined;
-  }
-
-  private static slug(valueArg: string): string {
-    return valueArg.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'nanoleaf';
-  }
-
-  private static isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
-  }
 }

package/ts/integrations/nanoleaf/nanoleaf.types.ts

@@ -1,160 +1,42 @@
-export type TNanoleafProtocol = 'http' | 'https';
-export type TNanoleafColorMode = 'hs' | 'ct' | 'effect' | string;
-export type TNanoleafGesture = 'swipe_up' | 'swipe_down' | 'swipe_left' | 'swipe_right';
+import type * as plugins from '../../plugins.js';
+import type { IConfigEncryptionKeyProvider } from '../../core/classes.configstore.js';
 
 export interface INanoleafConfig {
-  host?: string;
-  port?: number;
-  protocol?: TNanoleafProtocol;
-  authToken?: string;
-  token?: string;
-  controllerInfo?: INanoleafControllerInfo;
-  state?: INanoleafState;
-  effects?: INanoleafEffects;
-  panelLayout?: INanoleafPanelLayout;
-  rhythm?: INanoleafRhythmInfo;
-  snapshot?: INanoleafSnapshot;
-}
-
-export interface INanoleafValue<TValue> {
-  value: TValue;
-  min?: number;
-  max?: number;
-}
-
-export interface INanoleafState {
-  on?: INanoleafValue<boolean>;
-  brightness?: INanoleafValue<number>;
-  hue?: INanoleafValue<number>;
-  sat?: INanoleafValue<number>;
-  ct?: INanoleafValue<number>;
-  colorMode?: TNanoleafColorMode | INanoleafValue<TNanoleafColorMode>;
-}
-
-export interface INanoleafPanelInfo {
-  panelId: number;
-  x?: number;
-  y?: number;
-  o?: number;
-  shapeType?: number;
-}
-
-export interface INanoleafPanelLayout {
-  globalOrientation?: INanoleafValue<number>;
-  layout?: {
-    numPanels?: number;
-    sideLength?: number;
-    positionData?: INanoleafPanelInfo[];
-  };
-}
-
-export interface INanoleafRhythmInfo {
-  rhythmConnected?: boolean | INanoleafValue<boolean>;
-  rhythmActive?: boolean | INanoleafValue<boolean>;
-  rhythmId?: number | INanoleafValue<number>;
-  hardwareVersion?: string | INanoleafValue<string>;
-  firmwareVersion?: string | INanoleafValue<string>;
-  auxAvailable?: boolean | INanoleafValue<boolean>;
-  rhythmMode?: number | string | INanoleafValue<number | string>;
-  rhythmPos?: number | INanoleafValue<number>;
-}
-
-export interface INanoleafEffects {
-  select?: string;
-  effectsList?: string[];
-  write?: INanoleafEffectsCommand;
-}
-
-export interface INanoleafEffectPaletteColor {
-  hue?: number;
-  saturation?: number;
-  brightness?: number;
-  probability?: number;
-}
-
-export interface INanoleafEffectPluginOption {
-  name: string;
-  value?: string | number | boolean;
-  type?: string;
-  defaultValue?: string | number | boolean;
-  minValue?: number;
-  maxValue?: number;
-  strings?: string[];
-}
-
-export interface INanoleafEffectsCommand {
-  command: 'add' | 'request' | 'delete' | 'display' | 'displayTemp' | 'rename' | 'requestAll' | 'requestPlugins' | string;
-  version?: string;
-  duration?: number;
-  animName?: string;
-  newName?: string;
-  animType?: string;
-  animData?: string | null;
-  colorType?: string;
-  palette?: INanoleafEffectPaletteColor[];
-  Palette?: INanoleafEffectPaletteColor[];
-  pluginUuid?: string;
-  pluginType?: string;
-  pluginOptions?: INanoleafEffectPluginOption[];
-  loop?: boolean;
-  [key: string]: unknown;
-}
-
-export interface INanoleafStateCommand {
-  on?: INanoleafValue<boolean>;
-  brightness?: INanoleafValue<number> & { duration?: number; increment?: number };
-  hue?: INanoleafValue<number> & { increment?: number };
-  sat?: INanoleafValue<number> & { increment?: number };
-  ct?: INanoleafValue<number> & { increment?: number };
-}
-
-export interface INanoleafControllerInfo {
-  name?: string;
-  serialNo?: string;
-  manufacturer?: string;
-  firmwareVersion?: string;
-  hardwareVersion?: string;
-  model?: string;
-  state?: INanoleafState;
-  effects?: INanoleafEffects;
-  panelLayout?: INanoleafPanelLayout;
-  rhythm?: INanoleafRhythmInfo;
-}
-
-export interface INanoleafSnapshot {
-  controllerInfo: INanoleafControllerInfo;
-  state: INanoleafState;
-  effects: INanoleafEffects;
-  panelLayout?: INanoleafPanelLayout;
-  rhythm?: INanoleafRhythmInfo;
-}
-
-export interface INanoleafAuthTokenResult {
-  success: boolean;
-  authToken?: string;
-  error?: string;
+  homeId: string;
+  origin: string;
+  expectedSerialNumber: string;
+  expectedModel: string;
+  /** Existing token reference in the encrypted home/domain configuration store. */
+  credentialKey: string;
+  allowUnencryptedHttp?: boolean;
+  certificateAuthority?: string;
+  timeoutMs?: number;
+  maxResponseBytes?: number;
+  maxPendingOperations?: number;
 }
 
-export interface INanoleafEvent<TData = unknown> {
-  type: 'state' | 'effects' | 'layout' | 'touch' | string;
-  data: TData;
-  timestamp?: number;
+export interface INanoleafIntegrationOptions {
+  readonly homeId?: string;
+  readonly db?: plugins.nosqldb.SmartdataDb;
+  readonly keyProvider?: IConfigEncryptionKeyProvider;
 }
 
-export interface INanoleafStateEventData {
-  attribute: keyof INanoleafState | string;
-  value: unknown;
+export interface INanoleafCredential {
+  version: 1;
+  origin: string;
+  serialNumber: string;
+  model: string;
+  authToken: string;
 }
 
-export interface INanoleafEffectsEventData {
-  effect?: string;
-  effectsList?: string[];
+export interface INanoleafSnapshot extends plugins.ecobridgeDeviceManager.INanoleafSnapshot {
+  readonly homeId: string;
+  readonly origin: string;
 }
 
-export interface INanoleafTouchEventData {
-  panelId?: number;
-  gestureId?: number;
-  gesture?: TNanoleafGesture;
+export interface INanoleafWriteResult {
+  readonly acceptance: 'accepted';
+  readonly snapshot: INanoleafSnapshot;
 }
 
 export interface INanoleafMdnsRecord {

package/ts/integrations/nanoleaf/nanoleaf.validation.ts

@@ -0,0 +1,77 @@
+import * as plugins from '../../plugins.js';
+import type { INanoleafConfig } from './nanoleaf.types.js';
+
+export function nanoleafRecord(valueArg: unknown, nameArg: string): Record<string, unknown> {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+    throw new TypeError(`Nanoleaf ${nameArg} must be a plain data object.`);
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError(`Nanoleaf ${nameArg} may not contain symbols, accessors or hidden fields.`);
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function nanoleafKeys(recordArg: Record<string, unknown>, keysArg: readonly string[]): void {
+  if (Object.keys(recordArg).some((keyArg) => !keysArg.includes(keyArg))) throw new TypeError('Nanoleaf data contains unsupported fields.');
+}
+
+export function nanoleafText(valueArg: unknown, nameArg: string, maximumArg = 256): string {
+  if (typeof valueArg !== 'string' || !valueArg.trim() || valueArg.length > maximumArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`Nanoleaf ${nameArg} must be a bounded non-empty string without control characters.`);
+  }
+  return valueArg;
+}
+
+export function nanoleafInteger(valueArg: unknown, minimumArg: number, maximumArg: number, nameArg: string): number {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new TypeError(`Nanoleaf ${nameArg} must be an integer from ${minimumArg} through ${maximumArg}.`);
+  }
+  return valueArg;
+}
+
+export function normalizeNanoleafConfig(valueArg: unknown): Readonly<INanoleafConfig> {
+  const config = nanoleafRecord(valueArg, 'configuration');
+  nanoleafKeys(config, ['homeId', 'origin', 'expectedSerialNumber', 'expectedModel', 'credentialKey',
+    'allowUnencryptedHttp', 'certificateAuthority', 'timeoutMs', 'maxResponseBytes', 'maxPendingOperations']);
+  const homeId = nanoleafText(config.homeId, 'homeId');
+  const rawOrigin = nanoleafText(config.origin, 'origin', 2048);
+  let origin: URL;
+  try { origin = new URL(rawOrigin); } catch { throw new TypeError('Nanoleaf origin must be a selected local HTTP(S) origin.'); }
+  const [first, second, third, fourth] = origin.hostname.split('.').map(Number);
+  const selectedOrigin = /^https?:\/\/((?:[0-9]{1,3}\.){3}[0-9]{1,3})(?::([0-9]{1,5}))?\/?$/.exec(rawOrigin);
+  const local = plugins.net.isIP(origin.hostname) === 4 && (first === 10 || first === 127 ||
+    first === 192 && second === 168 || first === 172 && second >= 16 && second <= 31 || first === 169 && second === 254);
+  if (!local || fourth === 255 || first === 169 && second === 254 && (third === 0 || third === 255) ||
+    !selectedOrigin || selectedOrigin[1] !== origin.hostname || selectedOrigin[2] !== undefined && Number(selectedOrigin[2]) === 0 ||
+    origin.username || origin.password || origin.search || origin.hash || origin.pathname !== '/' ||
+    !['http:', 'https:'].includes(origin.protocol)) {
+    throw new TypeError('Nanoleaf origin must select one private, loopback or link-local unicast IPv4 HTTP(S) controller.');
+  }
+  if (config.allowUnencryptedHttp !== undefined && typeof config.allowUnencryptedHttp !== 'boolean') throw new TypeError('Nanoleaf HTTP consent must be a boolean.');
+  if (origin.protocol === 'http:' && config.allowUnencryptedHttp !== true) throw new TypeError('Nanoleaf plaintext HTTP requires explicit allowUnencryptedHttp: true consent.');
+  const expectedModel = nanoleafText(config.expectedModel, 'expectedModel', 64);
+  if (!plugins.ecobridgeDeviceManager.nanoleafSupportedModels.some((modelArg) => modelArg === expectedModel)) {
+    throw new TypeError('Nanoleaf expectedModel must identify a documented Light Panels API controller.');
+  }
+  const certificateAuthority = config.certificateAuthority;
+  if (certificateAuthority !== undefined && (typeof certificateAuthority !== 'string' || certificateAuthority.length > 524288 ||
+    !certificateAuthority.includes('-----BEGIN CERTIFICATE-----'))) throw new TypeError('Nanoleaf certificateAuthority must be a bounded PEM certificate.');
+  const credentialKey = nanoleafText(config.credentialKey, 'credentialKey');
+  if (encodeURIComponent(credentialKey).length > 900) throw new TypeError('Nanoleaf credentialKey exceeds the encrypted store key bound.');
+  return Object.freeze({
+    homeId, origin: origin.origin,
+    expectedSerialNumber: nanoleafText(config.expectedSerialNumber, 'expectedSerialNumber', 128), expectedModel,
+    credentialKey,
+    allowUnencryptedHttp: config.allowUnencryptedHttp === true,
+    certificateAuthority,
+    timeoutMs: nanoleafInteger(config.timeoutMs === undefined ? 5000 : config.timeoutMs, 1, 60000, 'timeoutMs'),
+    maxResponseBytes: nanoleafInteger(config.maxResponseBytes === undefined ? 1048576 : config.maxResponseBytes, 256, 1048576, 'maxResponseBytes'),
+    maxPendingOperations: nanoleafInteger(config.maxPendingOperations === undefined ? 32 : config.maxPendingOperations, 1, 64, 'maxPendingOperations'),
+  });
+}