@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/yeelight/yeelight.mapper.ts

@@ -1,219 +1,89 @@
 import * as plugins from '../../plugins.js';
 import type { IIntegrationEntity, IIntegrationEvent } from '../../core/types.js';
-import type { IYeelightBulbInfo, IYeelightBulbProperties, IYeelightEvent, IYeelightSnapshot } from './yeelight.types.js';
-
-const sensorProperties: Array<{ key: keyof IYeelightBulbProperties; name: string; unit?: string; binary?: boolean }> = [
-  { key: 'ct', name: 'Color temperature', unit: 'K' },
-  { key: 'rgb', name: 'RGB' },
-  { key: 'hue', name: 'Hue' },
-  { key: 'sat', name: 'Saturation', unit: '%' },
-  { key: 'color_mode', name: 'Color mode' },
-  { key: 'flowing', name: 'Color flow', binary: true },
-  { key: 'active_mode', name: 'Active mode' },
-  { key: 'nl_br', name: 'Nightlight brightness', unit: '%' },
-  { key: 'bg_power', name: 'Ambient power', binary: true },
-  { key: 'bg_bright', name: 'Ambient brightness', unit: '%' },
-  { key: 'bg_ct', name: 'Ambient color temperature', unit: 'K' },
-  { key: 'bg_rgb', name: 'Ambient RGB' },
-];
+import type { IYeelightBulbInfo, IYeelightEvent, IYeelightSnapshot } from './yeelight.types.js';
 
 export class YeelightMapper {
+  public static deviceId(homeIdArg: string, bulbIdArg: string): string {
+    return `yeelight.bulb.${encodeURIComponent(homeIdArg)}.${bulbIdArg}`;
+  }
+
+  public static entityId(homeIdArg: string, bulbIdArg: string): string {
+    return `light.yeelight.${encodeURIComponent(homeIdArg)}.${bulbIdArg}`;
+  }
+
   public static toDevices(snapshotArg: IYeelightSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
-    const updatedAt = new Date().toISOString();
     return snapshotArg.bulbs.map((bulbArg) => {
-      const state = this.bulbState(bulbArg);
-      const properties = bulbArg.properties || {};
-      const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
-        { id: 'power', capability: 'light', name: 'Power', readable: true, writable: true },
-      ];
-      const deviceState: plugins.shxInterfaces.data.IDeviceState[] = [
-        { featureId: 'power', value: state.on, updatedAt },
-      ];
-      if (state.brightness !== undefined || this.supports(bulbArg, 'set_bright')) {
-        features.push({ id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: true, unit: '%' });
-        deviceState.push({ featureId: 'brightness', value: state.brightness ?? null, updatedAt });
+      const properties = bulbArg.properties;
+      const online = snapshotArg.connected && bulbArg.available;
+      const features: plugins.shxInterfaces.data.IDeviceFeature[] = [];
+      const state: plugins.shxInterfaces.data.IDeviceState[] = [];
+      const add = (idArg: string, nameArg: string, valueArg: plugins.shxInterfaces.data.TDeviceStateValue,
+        writableArg: boolean, unitArg?: string): void => {
+        features.push({ id: idArg, capability: 'light', name: nameArg, readable: valueArg !== null, writable: online && writableArg, unit: unitArg });
+        state.push({ featureId: idArg, value: valueArg, updatedAt: snapshotArg.updatedAt });
+      };
+      add('power', 'Power', properties.power === 'on', bulbArg.support.includes('set_power'));
+      if (properties.bright !== undefined || bulbArg.support.includes('set_bright')) {
+        add('brightness', 'Brightness', properties.bright === undefined ? null : Number(properties.bright), bulbArg.support.includes('set_bright'), '%');
       }
-      if (state.colorTempKelvin !== undefined || this.supports(bulbArg, 'set_ct_abx')) {
-        features.push({ id: 'color_temperature', capability: 'light', name: 'Color temperature', readable: true, writable: true, unit: 'K' });
-        deviceState.push({ featureId: 'color_temperature', value: state.colorTempKelvin ?? null, updatedAt });
+      if (properties.color_mode === '1' || bulbArg.support.includes('set_rgb')) {
+        const rgb = properties.color_mode === '1' ? this.rgbValue(properties.rgb) : undefined;
+        add('rgb', 'RGB color', rgb ? rgb.join(',') : null, bulbArg.support.includes('set_rgb'));
       }
-      if (state.rgbColor !== undefined || this.supports(bulbArg, 'set_rgb')) {
-        features.push({ id: 'rgb', capability: 'light', name: 'RGB color', readable: true, writable: true });
-        deviceState.push({ featureId: 'rgb', value: state.rgbColor ? state.rgbColor.join(',') : null, updatedAt });
+      if (properties.color_mode === '2' && properties.ct !== undefined) {
+        add('color_temperature', 'Color temperature', Number(properties.ct), false, 'K');
       }
-      for (const sensor of sensorProperties) {
-        const value = properties[sensor.key];
-        if (value === undefined || value === null) {
-          continue;
-        }
-        const featureId = String(sensor.key);
-        if (features.some((featureArg) => featureArg.id === featureId)) {
-          continue;
+      for (const [key, name] of [['color_mode', 'Color mode'], ['flowing', 'Color flow']] as const) {
+        const value = properties[key];
+        if (value !== undefined) {
+          features.push({ id: key, capability: 'sensor', name, readable: true, writable: false });
+          state.push({ featureId: key, value: key === 'flowing' ? value === '1' : Number(value), updatedAt: snapshotArg.updatedAt });
         }
-        features.push({ id: featureId, capability: 'sensor', name: sensor.name, readable: true, writable: false, unit: sensor.unit });
-        deviceState.push({ featureId, value: this.deviceStateValue(sensor.binary ? this.binaryState(value) : this.propertyValue(value)), updatedAt });
       }
       return {
-        id: this.deviceId(bulbArg),
-        integrationDomain: 'yeelight',
-        name: this.bulbName(bulbArg),
-        protocol: 'unknown',
-        manufacturer: 'Yeelight',
-        model: bulbArg.model || bulbArg.capabilities?.model,
-        online: bulbArg.available !== false && (snapshotArg.connected || Boolean(bulbArg.properties)),
-        features,
-        state: deviceState,
-        metadata: {
-          host: bulbArg.host,
-          port: bulbArg.port || 55443,
-          firmwareVersion: bulbArg.fwVersion || bulbArg.capabilities?.fw_ver,
-          support: bulbArg.support || bulbArg.capabilities?.support?.split(' ').filter(Boolean),
-        },
+        id: this.deviceId(snapshotArg.homeId, bulbArg.id), integrationDomain: 'yeelight', name: bulbArg.name,
+        manufacturer: 'Yeelight', model: bulbArg.model, protocol: 'unknown', online, features, state,
+        metadata: { homeId: snapshotArg.homeId, vendorDeviceId: bulbArg.id, host: bulbArg.host, port: bulbArg.port,
+          firmwareVersion: bulbArg.fwVersion, supportedMethods: [...bulbArg.support],
+          observedAt: snapshotArg.updatedAt, transport: 'yeelight-lan-tcp', identityAssurance: 'unauthenticated-lan-identifier' },
       };
     });
   }
 
   public static toEntities(snapshotArg: IYeelightSnapshot): IIntegrationEntity[] {
-    const entities: IIntegrationEntity[] = [];
-    for (const bulb of snapshotArg.bulbs) {
-      const deviceId = this.deviceId(bulb);
-      const name = this.bulbName(bulb);
-      const slug = this.slug(name);
-      const state = this.bulbState(bulb);
-      entities.push({
-        id: `light.${slug}`,
-        uniqueId: `yeelight_${this.slug(bulb.id || bulb.host || name)}_light`,
-        integrationDomain: 'yeelight',
-        deviceId,
-        platform: 'light',
-        name,
-        state: state.on ? 'on' : 'off',
+    return snapshotArg.bulbs.map((bulbArg) => {
+      const properties = bulbArg.properties;
+      return {
+        id: this.entityId(snapshotArg.homeId, bulbArg.id), uniqueId: this.deviceId(snapshotArg.homeId, bulbArg.id),
+        integrationDomain: 'yeelight', deviceId: this.deviceId(snapshotArg.homeId, bulbArg.id), platform: 'light',
+        name: bulbArg.name, state: properties.power,
         attributes: {
-          brightness: state.brightness,
-          colorTempKelvin: state.colorTempKelvin,
-          rgbColor: state.rgbColor,
-          hsColor: state.hsColor,
-          colorMode: state.colorMode,
-          flowing: state.flowing,
-          nightLight: state.nightLight,
-          host: bulb.host,
-          model: bulb.model || bulb.capabilities?.model,
+          homeId: snapshotArg.homeId, brightness: properties.bright === undefined ? undefined : Number(properties.bright),
+          rgbColor: properties.color_mode === '1' ? this.rgbValue(properties.rgb) : undefined,
+          colorTempKelvin: properties.color_mode === '2' && properties.ct !== undefined ? Number(properties.ct) : undefined,
+          hsColor: properties.color_mode === '3' && properties.hue !== undefined && properties.sat !== undefined
+            ? [Number(properties.hue), Number(properties.sat)] : undefined,
+          colorMode: properties.color_mode, flowing: properties.flowing === undefined ? undefined : properties.flowing === '1',
+          supportedMethods: [...bulbArg.support], observedAt: snapshotArg.updatedAt,
         },
-        available: bulb.available !== false,
-      });
-      for (const sensor of sensorProperties) {
-        const value = bulb.properties?.[sensor.key];
-        if (value === undefined || value === null) {
-          continue;
-        }
-        const platform = sensor.binary ? 'binary_sensor' : 'sensor';
-        const sensorSlug = this.slug(`${name} ${sensor.name}`);
-        entities.push({
-          id: `${platform}.${sensorSlug}`,
-          uniqueId: `yeelight_${this.slug(bulb.id || bulb.host || name)}_${String(sensor.key)}`,
-          integrationDomain: 'yeelight',
-          deviceId,
-          platform,
-          name: `${name} ${sensor.name}`,
-          state: sensor.binary ? this.binaryState(value) ? 'on' : 'off' : this.propertyValue(value),
-          attributes: sensor.unit ? { unit: sensor.unit } : undefined,
-          available: bulb.available !== false,
-        });
-      }
-    }
-    return entities;
+        available: snapshotArg.connected && bulbArg.available,
+      };
+    });
   }
 
   public static toIntegrationEvent(eventArg: IYeelightEvent): IIntegrationEvent {
+    const bulb = eventArg.snapshot.bulbs[0];
     return {
-      type: eventArg.type === 'error' ? 'error' : 'state_changed',
-      integrationDomain: 'yeelight',
-      deviceId: eventArg.bulbId,
-      entityId: eventArg.entityId,
-      data: eventArg,
-      timestamp: eventArg.timestamp || Date.now(),
-    };
-  }
-
-  private static bulbState(bulbArg: IYeelightBulbInfo) {
-    if (bulbArg.state) {
-      return bulbArg.state;
-    }
-    const properties = bulbArg.properties || {};
-    const power = properties.main_power ?? properties.power;
-    const brightness = this.numberValue(properties.bright);
-    return {
-      on: power === 'on',
-      brightness,
-      colorTempKelvin: this.numberValue(properties.ct),
-      rgbColor: this.rgbValue(properties.rgb),
-      hsColor: this.hsValue(properties.hue, properties.sat),
-      colorMode: properties.color_mode === undefined || properties.color_mode === null ? undefined : String(properties.color_mode),
-      flowing: this.binaryState(properties.flowing),
-      nightLight: properties.active_mode !== undefined ? String(properties.active_mode) === '1' : this.numberValue(properties.nl_br) ? this.numberValue(properties.nl_br)! > 0 : undefined,
+      type: 'state_changed', integrationDomain: 'yeelight',
+      deviceId: bulb ? this.deviceId(eventArg.snapshot.homeId, bulb.id) : undefined,
+      entityId: bulb ? this.entityId(eventArg.snapshot.homeId, bulb.id) : undefined,
+      data: { snapshot: structuredClone(eventArg.snapshot) }, timestamp: eventArg.timestamp,
     };
   }
 
-  private static supports(bulbArg: IYeelightBulbInfo, commandArg: string): boolean {
-    const support = bulbArg.support || bulbArg.capabilities?.support?.split(' ').filter(Boolean) || [];
-    return support.includes(commandArg);
-  }
-
-  private static deviceId(bulbArg: IYeelightBulbInfo): string {
-    return `yeelight.bulb.${this.slug(bulbArg.id || bulbArg.host || this.bulbName(bulbArg))}`;
-  }
-
-  private static bulbName(bulbArg: IYeelightBulbInfo): string {
-    return bulbArg.name || bulbArg.properties?.name || bulbArg.capabilities?.name || bulbArg.model || bulbArg.host || 'Yeelight Bulb';
-  }
-
-  private static rgbValue(valueArg: unknown): [number, number, number] | undefined {
-    const numeric = this.numberValue(valueArg);
-    if (numeric === undefined) {
-      return undefined;
-    }
-    return [(numeric >> 16) & 0xff, (numeric >> 8) & 0xff, numeric & 0xff];
-  }
-
-  private static hsValue(hueArg: unknown, satArg: unknown): [number, number] | undefined {
-    const hue = this.numberValue(hueArg);
-    const sat = this.numberValue(satArg);
-    return hue === undefined || sat === undefined ? undefined : [hue, sat];
-  }
-
-  private static numberValue(valueArg: unknown): number | undefined {
-    if (typeof valueArg === 'number' && Number.isFinite(valueArg)) {
-      return valueArg;
-    }
-    if (typeof valueArg === 'string' && valueArg.trim() && Number.isFinite(Number(valueArg))) {
-      return Number(valueArg);
-    }
-    return undefined;
-  }
-
-  private static binaryState(valueArg: unknown): boolean {
-    return valueArg === true || valueArg === 'on' || valueArg === '1' || valueArg === 1;
-  }
-
-  private static propertyValue(valueArg: unknown): string | number | boolean | null {
-    const numeric = this.numberValue(valueArg);
-    if (numeric !== undefined) {
-      return numeric;
-    }
-    if (typeof valueArg === 'string' || typeof valueArg === 'boolean' || valueArg === null) {
-      return valueArg;
-    }
-    return valueArg === undefined ? null : String(valueArg);
-  }
-
-  private static deviceStateValue(valueArg: unknown): plugins.shxInterfaces.data.TDeviceStateValue {
-    if (typeof valueArg === 'string' || typeof valueArg === 'number' || typeof valueArg === 'boolean' || valueArg === null) {
-      return valueArg;
-    }
-    return String(valueArg);
-  }
-
-  private static slug(valueArg: string): string {
-    return valueArg.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'yeelight';
+  private static rgbValue(valueArg: string | undefined): [number, number, number] | undefined {
+    if (valueArg === undefined) return undefined;
+    const value = Number(valueArg);
+    return [(value >>> 16) & 255, (value >>> 8) & 255, value & 255];
   }
 }

package/ts/integrations/yeelight/yeelight.types.ts

@@ -1,196 +1,70 @@
-export type TYeelightPowerState = 'on' | 'off';
 export type TYeelightEffect = 'smooth' | 'sudden';
-export type TYeelightCommandMethod =
-  | 'get_prop'
-  | 'set_power'
-  | 'set_bright'
-  | 'set_ct_abx'
-  | 'set_rgb'
-  | 'set_hsv'
-  | 'set_scene'
-  | 'start_cf'
-  | 'stop_cf'
-  | 'set_default'
-  | 'set_name'
-  | 'toggle'
-  | string;
+export type TYeelightControl =
+  | { feature: 'power'; value: boolean }
+  | { feature: 'brightness'; value: number }
+  | { feature: 'rgb'; value: readonly [number, number, number] };
 
 export interface IYeelightConfig {
-  host?: string;
-  port?: number;
-  id?: string;
+  homeId: string;
+  host: string;
+  localAddress: string;
+  expectedId: string;
   name?: string;
-  model?: string;
-  detectedModel?: string;
-  detected_model?: string;
-  transition?: number;
+  discoveryPort?: number;
+  requestTimeoutMs?: number;
   effect?: TYeelightEffect;
-  snapshot?: IYeelightSnapshot;
-  bulb?: IYeelightBulbInfo;
-  bulbs?: IYeelightBulbInfo[];
-  devices?: Record<string, IYeelightManualDeviceConfig>;
-  commandExecutor?: TYeelightCommandExecutor;
-  [key: string]: unknown;
+  transitionMs?: number;
 }
 
 export interface IHomeAssistantYeelightConfig extends IYeelightConfig {}
 
-export interface IYeelightManualDeviceConfig {
-  id?: string;
-  name?: string;
-  model?: string;
-  detectedModel?: string;
-  detected_model?: string;
-  port?: number;
-  properties?: IYeelightBulbProperties;
-  capabilities?: IYeelightCapabilities;
-  [key: string]: unknown;
-}
-
-export interface IYeelightCapabilities {
-  id?: string;
-  location?: string;
-  model?: string;
-  fw_ver?: string;
-  support?: string;
-  power?: string;
+export interface IYeelightBulbProperties {
+  power: 'on' | 'off';
   bright?: string;
-  color_mode?: string;
   ct?: string;
   rgb?: string;
   hue?: string;
   sat?: string;
+  color_mode?: string;
+  flowing?: string;
   name?: string;
-  [key: string]: string | undefined;
-}
-
-export interface IYeelightBulbProperties {
-  power?: string | null;
-  main_power?: string | null;
-  bright?: string | null;
-  ct?: string | null;
-  rgb?: string | null;
-  hue?: string | null;
-  sat?: string | null;
-  color_mode?: string | null;
-  flowing?: string | null;
-  delayoff?: string | null;
-  music_on?: string | null;
-  name?: string | null;
-  bg_power?: string | null;
-  bg_flowing?: string | null;
-  bg_ct?: string | null;
-  bg_bright?: string | null;
-  bg_hue?: string | null;
-  bg_sat?: string | null;
-  bg_rgb?: string | null;
-  bg_lmode?: string | null;
-  nl_br?: string | null;
-  active_mode?: string | null;
-  current_brightness?: string | null;
-  [key: string]: string | number | boolean | null | undefined;
-}
-
-export interface IYeelightBulbState {
-  on: boolean;
-  brightness?: number;
-  colorTempKelvin?: number;
-  rgbColor?: [number, number, number];
-  hsColor?: [number, number];
-  colorMode?: string;
-  flowing?: boolean;
-  nightLight?: boolean;
 }
 
 export interface IYeelightBulbInfo {
-  id?: string;
-  host?: string;
-  port?: number;
-  name?: string;
-  model?: string;
+  id: string;
+  host: string;
+  port: number;
+  name: string;
+  model: string;
   fwVersion?: string;
-  support?: string[];
-  capabilities?: IYeelightCapabilities;
-  properties?: IYeelightBulbProperties;
-  state?: IYeelightBulbState;
-  available?: boolean;
-  metadata?: Record<string, unknown>;
+  support: readonly string[];
+  properties: IYeelightBulbProperties;
+  available: boolean;
 }
 
 export interface IYeelightSnapshot {
+  homeId: string;
   connected: boolean;
   bulbs: IYeelightBulbInfo[];
-  events: IYeelightEvent[];
-  source?: 'snapshot' | 'manual' | 'tcp';
-  updatedAt?: string;
-}
-
-export interface IYeelightCommand {
-  id?: number;
-  method: TYeelightCommandMethod;
-  params?: unknown[];
-  host?: string;
-  port?: number;
+  updatedAt: string;
 }
 
-export interface IYeelightCommandResponse {
-  id?: number;
-  result?: unknown[];
-  error?: unknown;
-  method?: string;
-  params?: Record<string, unknown>;
-}
-
-export interface IYeelightCommandResult {
-  success: boolean;
-  error?: string;
-  data?: unknown;
-}
-
-export interface IYeelightLightStatePatch {
-  on?: boolean;
-  brightness?: number;
-  percentage?: number;
-  colorTempKelvin?: number;
-  rgbColor?: [number, number, number];
-  transition?: number;
-  effect?: TYeelightEffect;
-}
-
-export type TYeelightCommandExecutor = (
-  commandArg: IYeelightCommand
-) => Promise<IYeelightCommandResponse | IYeelightCommandResult | unknown> | IYeelightCommandResponse | IYeelightCommandResult | unknown;
-
 export interface IYeelightEvent {
-  type: 'properties' | 'command' | 'error';
-  timestamp?: number;
-  bulbId?: string;
-  host?: string;
-  entityId?: string;
-  command?: IYeelightCommand;
-  data?: unknown;
-  error?: string;
-  [key: string]: unknown;
+  type: 'properties';
+  snapshot: IYeelightSnapshot;
+  timestamp: number;
 }
 
 export interface IYeelightSsdpRecord {
   location?: string;
-  Location?: string;
   id?: string;
-  Id?: string;
   model?: string;
-  Model?: string;
   support?: string;
-  Support?: string;
   st?: string;
-  ST?: string;
-  usn?: string;
-  USN?: string;
-  server?: string;
-  Server?: string;
-  ssdp_headers?: Record<string, string | undefined>;
+  name?: string;
+  fw_ver?: string;
   headers?: Record<string, string | undefined>;
-  [key: string]: unknown;
+  ssdp_headers?: Record<string, string | undefined>;
 }
 
 export interface IYeelightMdnsRecord {
@@ -206,13 +80,8 @@ export interface IYeelightMdnsRecord {
 
 export interface IYeelightManualEntry {
   host?: string;
-  port?: number;
   id?: string;
   name?: string;
   model?: string;
   manufacturer?: string;
-  properties?: IYeelightBulbProperties;
-  capabilities?: IYeelightCapabilities;
-  snapshot?: IYeelightSnapshot;
-  metadata?: Record<string, unknown>;
 }

package/ts/integrations/yeelight/yeelight.validation.ts

@@ -0,0 +1,112 @@
+import * as plugins from '../../plugins.js';
+import type { IConfigStore } from '../../core/types.js';
+import type { IYeelightBulbProperties, IYeelightConfig, TYeelightControl } from './yeelight.types.js';
+
+export const yeelightRecord = (valueArg: unknown, keysArg: readonly string[]): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+    throw new TypeError('Yeelight input must be a plain object.');
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !keysArg.includes(key) || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError('Yeelight input contains an unsupported field or accessor.');
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true, configurable: true, writable: true });
+  }
+  return result;
+};
+
+export const yeelightText = (valueArg: unknown, nameArg: string, maximumArg = 256): string => {
+  if (typeof valueArg !== 'string' || valueArg.length === 0 || valueArg.length > maximumArg ||
+    valueArg !== valueArg.trim() || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`Yeelight ${nameArg} must be bounded text without control characters.`);
+  }
+  return valueArg;
+};
+
+export const yeelightId = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string' || !/^0x[0-9a-f]{1,64}$/i.test(valueArg)) {
+    throw new TypeError('Yeelight expectedId must be the hexadecimal vendor discovery identifier.');
+  }
+  return valueArg.toLowerCase();
+};
+
+export const yeelightAddress = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string' || plugins.net.isIP(valueArg) !== 4) {
+    throw new TypeError('Yeelight endpoints require an explicit local unicast IPv4 address.');
+  }
+  const parts = valueArg.split('.').map(Number);
+  const local = parts[0] === 10 || parts[0] === 127 ||
+    (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) ||
+    (parts[0] === 192 && parts[1] === 168) || (parts[0] === 169 && parts[1] === 254);
+  if (!local) {
+    throw new TypeError('Yeelight endpoints must be private, link-local or loopback IPv4 addresses.');
+  }
+  return valueArg;
+};
+
+const integer = (valueArg: unknown, fallbackArg: number, minimumArg: number, maximumArg: number, nameArg: string): number => {
+  const value = valueArg ?? fallbackArg;
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimumArg || value > maximumArg) {
+    throw new RangeError(`Yeelight ${nameArg} must be an integer from ${minimumArg} through ${maximumArg}.`);
+  }
+  return value;
+};
+
+export const normalizeYeelightConfig = (configArg: unknown): Readonly<Required<Omit<IYeelightConfig, 'name'>> & Pick<IYeelightConfig, 'name'>> => {
+  const config = yeelightRecord(configArg, ['homeId', 'host', 'localAddress', 'expectedId', 'name', 'discoveryPort', 'requestTimeoutMs', 'effect', 'transitionMs']);
+  const effect = config.effect ?? 'smooth';
+  if (effect !== 'smooth' && effect !== 'sudden') throw new TypeError('Yeelight effect must be smooth or sudden.');
+  return Object.freeze({
+    homeId: yeelightText(config.homeId, 'homeId'), host: yeelightAddress(config.host),
+    localAddress: yeelightAddress(config.localAddress), expectedId: yeelightId(config.expectedId),
+    name: config.name === undefined ? undefined : yeelightText(config.name, 'name', 128),
+    discoveryPort: integer(config.discoveryPort, 1982, 1, 65535, 'discoveryPort'),
+    requestTimeoutMs: integer(config.requestTimeoutMs, 5000, 1, 60000, 'requestTimeoutMs'), effect,
+    transitionMs: integer(config.transitionMs, 350, effect === 'smooth' ? 30 : 0, 60000, 'transitionMs'),
+  });
+};
+
+export const assertYeelightScope = (storeArg: IConfigStore | undefined, homeIdArg: string): void => {
+  if (!storeArg || typeof storeArg.getScope !== 'function') throw new Error('Yeelight requires a home-scoped config store.');
+  const scope = yeelightRecord(storeArg.getScope(), ['homeId', 'integrationDomain']);
+  if (scope.homeId !== homeIdArg || scope.integrationDomain !== 'yeelight') throw new Error('Yeelight config store scope does not match the configured home and integration.');
+};
+
+const decimalProperty = (valueArg: unknown, minimumArg: number, maximumArg: number): string | undefined => {
+  if (valueArg === undefined || valueArg === '') return undefined;
+  if (typeof valueArg !== 'string' || !/^(0|[1-9]\d*)$/.test(valueArg)) throw new Error('Yeelight returned a malformed numeric property.');
+  const value = Number(valueArg);
+  if (!Number.isSafeInteger(value) || value < minimumArg || value > maximumArg) throw new Error('Yeelight returned an out-of-range numeric property.');
+  return valueArg;
+};
+
+export const parseYeelightProperties = (propertiesArg: Readonly<Record<string, string>>): IYeelightBulbProperties => {
+  if (propertiesArg.power !== 'on' && propertiesArg.power !== 'off') throw new Error('Yeelight returned an invalid authoritative power state.');
+  const name = propertiesArg.name === undefined || propertiesArg.name === '' ? undefined : yeelightText(propertiesArg.name, 'reported name', 128);
+  return {
+    power: propertiesArg.power,
+    bright: decimalProperty(propertiesArg.bright, 1, 100), rgb: decimalProperty(propertiesArg.rgb, 0, 16777215),
+    ct: decimalProperty(propertiesArg.ct, 1, 65535), hue: decimalProperty(propertiesArg.hue, 0, 359),
+    sat: decimalProperty(propertiesArg.sat, 0, 100), color_mode: decimalProperty(propertiesArg.color_mode, 1, 3),
+    flowing: decimalProperty(propertiesArg.flowing, 0, 1), name,
+  };
+};
+
+export const validateYeelightControl = (controlArg: unknown): TYeelightControl => {
+  const control = yeelightRecord(controlArg, ['feature', 'value']);
+  if (control.feature === 'power' && typeof control.value === 'boolean') return { feature: 'power', value: control.value };
+  if (control.feature === 'brightness') return { feature: 'brightness', value: integer(control.value, 0, 1, 100, 'brightness') };
+  if (control.feature === 'rgb' && Array.isArray(control.value) && control.value.length === 3 &&
+    Object.keys(control.value).length === 3 && Reflect.ownKeys(control.value).length === 4) {
+    const values = [0, 1, 2].map((indexArg) => {
+      const descriptor = Object.getOwnPropertyDescriptor(control.value, String(indexArg));
+      if (!descriptor || !('value' in descriptor)) throw new TypeError('Yeelight RGB may not contain holes or accessors.');
+      return integer(descriptor.value, -1, 0, 255, 'RGB channel');
+    });
+    return { feature: 'rgb', value: [values[0], values[1], values[2]] };
+  }
+  throw new TypeError('Yeelight supports one exact power, brightness or RGB control per operation.');
+};

package/ts/integrations/zha/readme.md

@@ -0,0 +1,23 @@
+# ZHA coordinator discovery
+
+This domain recognizes Zigbee coordinator candidates. Its current runtime maps supplied snapshots and optional caller-provided command executors. It does not connect to a coordinator, interview devices, receive live Zigbee state, or implement ZHA's Python quirks. Discovery validation does not establish physical radio compatibility or authorize access to a home.
+
+USB discovery requires both a known VID/PID pair and a matching coordinator product description from the [Home Assistant ZHA manifest](https://github.com/home-assistant/core/blob/dev/homeassistant/components/zha/manifest.json), plus a serial endpoint. Common CP2102 and CH340 USB bridge identifiers alone are insufficient. Serial numbers do not identify a radio model.
+
+Network discovery requires the manifest's service type and instance-name pattern, plus a valid host and port. Arbitrary `radio_type` and `serial_number` TXT fields on unrelated services do not qualify. Legacy ESPHome announcements qualify only for the manifest's `tube*` coordinator instance names. Candidate metadata excludes arbitrary TXT fields, credentials, supplied snapshots, database paths, and nested caller metadata. These unauthenticated discovery advertisements remain identity hints, reported with `high` confidence rather than a verified radio handshake.
+
+Manual selection accepts an explicitly selected ZHA serial path or `socket://host:port` endpoint. POSIX paths must be below `/dev/`; Windows `COM` device names are accepted. Relative paths, traversal segments, URL credentials, URL paths or query strings, invalid hosts, invalid ports, and contradictory endpoint aliases are rejected. IPv6 socket addresses are bracketed. Manual candidates have `medium` confidence. Other integration domains and unsupported discovery sources are rejected by the candidate validator.
+
+## Native runtime boundary
+
+The [ZHA documentation](https://www.home-assistant.io/integrations/zha/) describes a coordinator backed by the `zigpy` radio libraries. No Python bridge is introduced here. The published Node.js alternative, [zigbee-herdsman](https://github.com/Koenkk/zigbee-herdsman), was inspected on 2026-10-06 at versions `10.9.5` and `11.0.0`. Version `10.9.5` is the newest publication that meets the effective seven-day release-age policy at the inspection time. Version `10.9.6` becomes eligible on 2026-10-06 at 18:21:25 UTC. No dependency was added.
+
+Both inspected versions require path-based `databasePath`, `databaseBackupPath`, and `backupPath` controller options. Their controller opens its database internally, and the [database implementation](https://github.com/Koenkk/zigbee-herdsman/blob/master/src/controller/database.ts) persists entries with synchronous filesystem operations. `Entity` stores the injected adapter and database statically; `Device` and `Group` maintain static caches. The public controller API provides neither a supported external storage provider nor isolated per-controller model state. Using a temporary database, monkey-patching storage, or copying that implementation into this consumer would leave the owning defect unresolved.
+
+The reusable transport owner must first provide:
+
+- An awaited storage-provider contract for device/network records and coordinator backups, so `@lossless.org/client` can durably store state and encrypted key material without application filesystem persistence.
+- Controller-owned adapter, database, device, group, and lookup state, with tests proving concurrent networks cannot share identities, credentials, or commands.
+- Resource lifecycle and cancellation contracts that drain admitted work before close and expose failures to the caller.
+
+After those capabilities are published, this domain can consume them and verify coordinator setup, authoritative attribute reports, endpoint-specific supported controls, recovery, and cleanup with protocol fixtures. Physical coordinator acceptance requires separately authorized hardware access. Native Zigbee support remains incomplete.