@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/yeelight/yeelight.classes.integration.ts

@@ -1,11 +1,12 @@
-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 { YeelightClient } from './yeelight.classes.client.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { YeelightClient, YeelightControlError } from './yeelight.classes.client.js';
 import { YeelightConfigFlow } from './yeelight.classes.configflow.js';
 import { createYeelightDiscoveryDescriptor } from './yeelight.discovery.js';
 import { YeelightMapper } from './yeelight.mapper.js';
-import type { IYeelightConfig, IYeelightLightStatePatch } from './yeelight.types.js';
+import type { IYeelightConfig, TYeelightControl } from './yeelight.types.js';
+import { validateYeelightControl, yeelightRecord } from './yeelight.validation.js';
 
 export class YeelightIntegration extends BaseIntegration<IYeelightConfig> {
   public readonly domain = 'yeelight';
@@ -14,118 +15,145 @@ export class YeelightIntegration extends BaseIntegration<IYeelightConfig> {
   public readonly discoveryDescriptor = createYeelightDiscoveryDescriptor();
   public readonly configFlow = new YeelightConfigFlow();
   public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/yeelight',
-    upstreamDomain: 'yeelight',
-    integrationType: 'device',
-    iotClass: 'local_push',
-    documentation: 'https://www.home-assistant.io/integrations/yeelight',
-    requirements: ['yeelight==0.7.16', 'async-upnp-client==0.46.2'],
-    dependencies: ['network'],
-    afterDependencies: ['ssdp'],
-    codeowners: ['@zewelor', '@shenxn', '@starkillerOG', '@alexyao2015'],
+    source: 'home-assistant/core', upstreamPath: 'homeassistant/components/yeelight', upstreamDomain: 'yeelight',
+    integrationType: 'device', iotClass: 'local_push', documentation: 'https://www.home-assistant.io/integrations/yeelight',
+    localApi: { implemented: ['targeted vendor discovery', 'home-scoped admission', 'authoritative TCP properties', 'power, brightness and RGB controls'],
+      explicitUnsupported: ['injected runtime clients or snapshots', 'arbitrary commands', 'colour temperature writes', 'scenes and music mode', 'compound effects', 'automatic retries or reconnects'] },
   };
+  private readonly clients = new Set<YeelightClient>();
+  private readonly runtimes = new Set<YeelightRuntime>();
+  private readonly setups = new Set<Promise<IIntegrationRuntime>>();
+  private closePromise?: Promise<void>;
+  private closed = false;
 
-  public async setup(configArg: IYeelightConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new YeelightRuntime(new YeelightClient(configArg));
+  public setup(configArg: IYeelightConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    if (this.closed) return Promise.reject(new Error('Yeelight integration is closed.'));
+    const setup = this.createRuntime(configArg, contextArg).finally(() => { this.setups.delete(setup); });
+    this.setups.add(setup);
+    return setup;
   }
 
-  public async destroy(): Promise<void> {}
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.closed = true;
+      const cleanup = [...[...this.runtimes].map((runtimeArg) => runtimeArg.destroy()),
+        ...[...this.clients].map((clientArg) => clientArg.destroy())];
+      this.closePromise = Promise.allSettled([...cleanup, ...this.setups]).then((resultsArg) => {
+        const errors = resultsArg.slice(0, cleanup.length).flatMap((resultArg) => resultArg.status === 'rejected' ? [resultArg.reason as unknown] : []);
+        if (errors.length) throw new AggregateError(errors, 'Yeelight integration cleanup failed.');
+      });
+    }
+    return this.closePromise;
+  }
+
+  private async createRuntime(configArg: IYeelightConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    const client = new YeelightClient(configArg, contextArg.configStore);
+    this.clients.add(client);
+    try {
+      await client.start(contextArg.abortSignal);
+      if (this.closed) throw new Error('Yeelight integration is closed.');
+      const runtime = new YeelightRuntime(client, () => { this.runtimes.delete(runtime); this.clients.delete(client); });
+      this.runtimes.add(runtime);
+      return runtime;
+    } catch (errorArg) {
+      try { await client.destroy(); }
+      catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'Yeelight setup and cleanup failed.'); }
+      this.clients.delete(client);
+      throw errorArg;
+    }
+  }
 }
 
 export class HomeAssistantYeelightIntegration extends YeelightIntegration {}
 
 class YeelightRuntime implements IIntegrationRuntime {
-  public domain = 'yeelight';
+  public readonly domain = 'yeelight';
+  private readonly disposers = new Set<() => void>();
+  private closePromise?: Promise<void>;
 
-  constructor(private readonly client: YeelightClient) {}
+  public constructor(private readonly client: YeelightClient, private readonly onDestroyed: () => void) {}
+  public isHealthy(): boolean { return this.client.isHealthy(); }
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return YeelightMapper.toDevices(await this.client.getSnapshot());
+  public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return YeelightMapper.toDevices(await this.client.getSnapshot(abortSignalArg));
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
     return YeelightMapper.toEntities(await this.client.getSnapshot());
   }
 
-  public async subscribe(handlerArg: (eventArg: ReturnType<typeof YeelightMapper.toIntegrationEvent>) => void): Promise<() => Promise<void>> {
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    if (abortSignalArg !== undefined && !(abortSignalArg instanceof AbortSignal)) throw new TypeError('Yeelight subscription requires an AbortSignal.');
+    abortSignalArg?.throwIfAborted();
     const unsubscribe = this.client.onEvent((eventArg) => handlerArg(YeelightMapper.toIntegrationEvent(eventArg)));
-    return async () => unsubscribe();
+    const dispose = (): void => {
+      unsubscribe();
+      abortSignalArg?.removeEventListener('abort', dispose);
+      this.disposers.delete(dispose);
+    };
+    this.disposers.add(dispose);
+    abortSignalArg?.addEventListener('abort', dispose, { once: true });
+    if (abortSignalArg?.aborted) dispose();
+    return async () => dispose();
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (!['light', 'number'].includes(requestArg.domain)) {
-      return { success: false, error: `Unsupported Yeelight service domain: ${requestArg.domain}` };
-    }
-    const patch = this.patchForService(requestArg);
-    if (!patch) {
-      return { success: false, error: `Unsupported Yeelight service: ${requestArg.service}` };
-    }
-    await this.client.setLightState(patch);
-    return { success: true };
+    try {
+      const request = yeelightRecord(requestArg, ['domain', 'service', 'target', 'data']);
+      if (request.domain !== 'light') throw new Error('Unsupported domain.');
+      const target = yeelightRecord(request.target, ['deviceId', 'entityId']);
+      const deviceId = YeelightMapper.deviceId(this.client.homeId, this.client.bulbId);
+      const entityId = YeelightMapper.entityId(this.client.homeId, this.client.bulbId);
+      if ((target.deviceId === undefined && target.entityId === undefined) ||
+        (target.deviceId !== undefined && target.deviceId !== deviceId) ||
+        (target.entityId !== undefined && target.entityId !== entityId)) throw new Error('Foreign or missing target.');
+      const data = yeelightRecord(request.data ?? {}, ['brightness', 'rgbColor']);
+      let control: TYeelightControl;
+      if ((request.service === 'turn_on' || request.service === 'turn_off') && Object.keys(data).length === 0) {
+        control = { feature: 'power', value: request.service === 'turn_on' };
+      } else if (request.service === 'set_brightness' && Object.keys(data).length === 1 && typeof data.brightness === 'number') {
+        control = validateYeelightControl({ feature: 'brightness', value: data.brightness });
+      } else if (request.service === 'set_rgb' && Object.keys(data).length === 1) {
+        control = validateYeelightControl({ feature: 'rgb', value: data.rgbColor });
+      } else throw new Error('Unsupported or compound control.');
+      return await this.execute(control);
+    } catch (errorArg) { return this.failure(errorArg); }
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const request = yeelightRecord(requestArg, ['device', 'feature', 'value']);
+      const suppliedDevice = yeelightRecord(request.device, ['id', 'integrationDomain', 'name', 'room', 'protocol', 'manufacturer', 'model', 'online', 'features', 'state', 'metadata']);
+      const suppliedFeature = yeelightRecord(request.feature, ['id', 'capability', 'name', 'readable', 'writable', 'unit']);
+      const device = YeelightMapper.toDevices(this.client.getObservedSnapshot())[0];
+      if (suppliedDevice.id !== device.id || suppliedDevice.integrationDomain !== this.domain) throw new Error('Foreign target.');
+      const feature = device.features.find((featureArg) => featureArg.id === suppliedFeature.id);
+      if (!feature?.writable || feature.capability !== suppliedFeature.capability) throw new Error('Unsupported feature.');
+      let control: TYeelightControl;
+      if (feature.id === 'power' && typeof request.value === 'boolean') control = { feature: 'power', value: request.value };
+      else if (feature.id === 'brightness' && typeof request.value === 'number') control = { feature: 'brightness', value: request.value };
+      else if (feature.id === 'rgb' && typeof request.value === 'string' && /^(0|[1-9]\d{0,2}),(0|[1-9]\d{0,2}),(0|[1-9]\d{0,2})$/.test(request.value)) {
+        control = validateYeelightControl({ feature: 'rgb', value: request.value.split(',').map(Number) });
+      } else throw new Error('Invalid feature value.');
+      return await this.execute(validateYeelightControl(control), abortSignalArg);
+    } catch (errorArg) { return this.failure(errorArg); }
   }
 
-  private patchForService(requestArg: IServiceCallRequest): IYeelightLightStatePatch | undefined {
-    if (requestArg.service === 'turn_on') {
-      return { on: true, ...this.patchFromData(requestArg.data) };
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      for (const dispose of [...this.disposers]) dispose();
+      this.closePromise = this.client.destroy().then(this.onDestroyed);
     }
-    if (requestArg.service === 'turn_off') {
-      return { on: false, transition: this.numberValue(requestArg.data?.transition) };
-    }
-    if (requestArg.service === 'set_brightness' || requestArg.service === 'set_percentage') {
-      const value = this.numberValue(requestArg.data?.brightness ?? requestArg.data?.percentage ?? requestArg.data?.value);
-      return value === undefined ? undefined : { percentage: value, transition: this.numberValue(requestArg.data?.transition) };
-    }
-    if (requestArg.service === 'set_value') {
-      const property = String(requestArg.data?.property || requestArg.data?.attribute || '').toLowerCase();
-      const value = requestArg.data?.value;
-      if (property === 'rgb' || property === 'rgb_color') {
-        const rgb = this.rgbValue(value);
-        return rgb ? { rgbColor: rgb, transition: this.numberValue(requestArg.data?.transition) } : undefined;
-      }
-      if (property === 'ct' || property === 'color_temp' || property === 'color_temp_kelvin' || property === 'kelvin') {
-        const kelvin = this.numberValue(value);
-        return kelvin === undefined ? undefined : { colorTempKelvin: kelvin, transition: this.numberValue(requestArg.data?.transition) };
-      }
-      const numeric = this.numberValue(value);
-      return numeric === undefined ? undefined : { percentage: numeric, transition: this.numberValue(requestArg.data?.transition) };
-    }
-    return undefined;
+    return this.closePromise;
   }
 
-  private patchFromData(dataArg?: Record<string, unknown>): IYeelightLightStatePatch {
-    const rgb = this.rgbValue(dataArg?.rgbColor ?? dataArg?.rgb_color);
-    return {
-      brightness: this.numberValue(dataArg?.brightness),
-      percentage: this.numberValue(dataArg?.percentage),
-      colorTempKelvin: this.numberValue(dataArg?.colorTempKelvin ?? dataArg?.color_temp_kelvin ?? dataArg?.kelvin),
-      rgbColor: rgb,
-      transition: this.numberValue(dataArg?.transition),
-    };
+  private async execute(controlArg: TYeelightControl, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    await this.client.setControl(controlArg, signalArg);
+    return { success: true, data: { effectOutcome: 'acknowledged' } };
   }
 
-  private rgbValue(valueArg: unknown): [number, number, number] | undefined {
-    if (!Array.isArray(valueArg) || valueArg.length < 3) {
-      return undefined;
-    }
-    const red = this.numberValue(valueArg[0]);
-    const green = this.numberValue(valueArg[1]);
-    const blue = this.numberValue(valueArg[2]);
-    return red === undefined || green === undefined || blue === undefined ? undefined : [red, green, blue];
-  }
-
-  private 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 failure(errorArg: unknown): IServiceCallResult {
+    return { success: false, error: 'Yeelight control was refused or its outcome could not be reconciled.',
+      data: { effectOutcome: errorArg instanceof YeelightControlError ? errorArg.effectOutcome : 'not-sent' } };
   }
 }

package/ts/integrations/yeelight/yeelight.discovery.ts

@@ -1,170 +1,108 @@
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
 import type { IYeelightManualEntry, IYeelightMdnsRecord, IYeelightSsdpRecord } from './yeelight.types.js';
+import { yeelightAddress, yeelightId, yeelightRecord, yeelightText } from './yeelight.validation.js';
 
-const defaultPort = 55443;
+const unmatched = (reasonArg: string): IDiscoveryMatch => ({ matched: false, confidence: 'low', reason: reasonArg });
 
 export class YeelightSsdpMatcher implements IDiscoveryMatcher<IYeelightSsdpRecord> {
-  public id = 'yeelight-ssdp-match';
-  public source = 'ssdp' as const;
-  public description = 'Recognize Yeelight local LAN SSDP wifi_bulb responses.';
+  public readonly id = 'yeelight-ssdp-match';
+  public readonly source = 'ssdp' as const;
+  public readonly description = 'Recognize vendor wifi_bulb discovery hints; setup performs fresh targeted admission.';
 
   public async matches(recordArg: IYeelightSsdpRecord): Promise<IDiscoveryMatch> {
-    const headers = this.normalizedHeaders(recordArg);
-    const location = headers.location;
-    const support = headers.support || '';
-    if (!headers.id || !location || !(headers.st === 'wifi_bulb' || support.includes('set_power') || headers.model)) {
-      return { matched: false, confidence: 'low', reason: 'SSDP response is not a Yeelight wifi_bulb advertisement.' };
-    }
-    const endpoint = this.parseLocation(location);
-    return {
-      matched: true,
-      confidence: headers.id && endpoint.host ? 'certain' : 'high',
-      reason: 'SSDP response contains Yeelight LAN control capabilities.',
-      normalizedDeviceId: headers.id,
-      candidate: {
-        source: 'ssdp',
-        integrationDomain: 'yeelight',
-        id: headers.id,
-        host: endpoint.host,
-        port: endpoint.port || defaultPort,
-        name: headers.name,
-        manufacturer: 'Yeelight',
-        model: headers.model,
-        metadata: {
-          location,
-          support: support.split(' ').filter(Boolean),
-          firmwareVersion: headers.fw_ver,
-          capabilities: headers,
-        },
-      },
-    };
-  }
-
-  private normalizedHeaders(recordArg: IYeelightSsdpRecord): Record<string, string | undefined> {
-    const source = { ...recordArg.headers, ...recordArg.ssdp_headers, ...recordArg } as Record<string, unknown>;
-    const normalized: Record<string, string | undefined> = {};
-    for (const [key, value] of Object.entries(source)) {
-      if (typeof value === 'string') {
-        normalized[key.toLowerCase()] = value;
-      }
-    }
-    return normalized;
-  }
-
-  private parseLocation(locationArg: string): { host?: string; port?: number } {
     try {
-      const parsed = new URL(locationArg);
-      return { host: parsed.hostname, port: parsed.port ? Number(parsed.port) : undefined };
-    } catch {
-      const match = locationArg.match(/([0-9a-z.-]+):(\d+)/i);
-      return match ? { host: match[1], port: Number(match[2]) } : {};
-    }
+      const record = yeelightRecord(recordArg, ['location', 'id', 'model', 'support', 'st', 'name', 'fw_ver', 'headers', 'ssdp_headers']);
+      const headers: Record<string, string> = {};
+      for (const block of [record.headers, record.ssdp_headers, record]) {
+        if (block === undefined) continue;
+        const entries = yeelightRecord(block, Object.getOwnPropertyNames(block));
+        for (const [key, value] of Object.entries(entries)) {
+          if (key === 'headers' || key === 'ssdp_headers') continue;
+          if (typeof value !== 'string' || value.length > 1024) throw new TypeError('Invalid discovery header.');
+          const normalized = key.toLowerCase();
+          if (headers[normalized] !== undefined && headers[normalized] !== value) throw new TypeError('Conflicting discovery headers.');
+          headers[normalized] = value;
+        }
+      }
+      if (headers.st !== 'wifi_bulb') return unmatched('Not a vendor wifi_bulb discovery hint.');
+      const endpoint = new URL(headers.location);
+      if (endpoint.protocol !== 'yeelight:' || endpoint.username || endpoint.password || endpoint.pathname || endpoint.search || endpoint.hash || !endpoint.port) {
+        return unmatched('Invalid Yeelight LAN discovery endpoint.');
+      }
+      const id = yeelightId(headers.id);
+      const host = yeelightAddress(endpoint.hostname);
+      const model = yeelightText(headers.model, 'discovered model', 128);
+      return { matched: true, confidence: 'high', reason: 'Unauthenticated Yeelight setup hint; fresh ID admission is still required.',
+        normalizedDeviceId: id, candidate: { source: 'ssdp', integrationDomain: 'yeelight', id, host,
+          port: Number(endpoint.port), manufacturer: 'Yeelight', model, name: headers.name,
+          metadata: { discoveryHint: true } } };
+    } catch { return unmatched('Invalid Yeelight discovery hint.'); }
   }
 }
 
 export class YeelightMdnsMatcher implements IDiscoveryMatcher<IYeelightMdnsRecord> {
-  public id = 'yeelight-mdns-match';
-  public source = 'mdns' as const;
-  public description = 'Recognize Yeelight zeroconf records from yeelink names and _miio._udp.local.';
+  public readonly id = 'yeelight-mdns-match';
+  public readonly source = 'mdns' as const;
+  public readonly description = 'Recognize Yeelight metadata without treating generic Xiaomi mDNS as a control capability.';
 
   public async matches(recordArg: IYeelightMdnsRecord): Promise<IDiscoveryMatch> {
-    const type = (recordArg.type || '').toLowerCase().replace(/\.$/, '');
-    const name = (recordArg.name || recordArg.hostname || '').toLowerCase();
-    const txt = recordArg.txt || recordArg.properties || {};
-    const model = txt.model || txt.modelid || recordArg.txt?.md || undefined;
-    const matched = name.startsWith('yeelink-') || type === '_miio._udp.local' || Boolean(model?.startsWith('YL'));
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'mDNS record is not a Yeelight advertisement.' };
-    }
-    const host = recordArg.host || recordArg.hostname || recordArg.addresses?.[0];
-    const deviceId = txt.id || txt.mac || txt.serial || recordArg.name || host;
-    return {
-      matched: true,
-      confidence: host ? 'high' : 'medium',
-      reason: 'mDNS record matches Yeelight zeroconf metadata.',
-      normalizedDeviceId: deviceId,
-      candidate: {
-        source: 'mdns',
-        integrationDomain: 'yeelight',
-        id: deviceId,
-        host,
-        port: recordArg.port || defaultPort,
-        name: recordArg.name,
-        manufacturer: 'Yeelight',
-        model,
-        metadata: {
-          mdnsName: recordArg.name,
-          mdnsType: recordArg.type,
-          txt,
-        },
-      },
-    };
+    try {
+      const record = yeelightRecord(recordArg, ['type', 'name', 'host', 'hostname', 'addresses', 'port', 'txt', 'properties']);
+      const txt = record.txt === undefined && record.properties === undefined ? {} :
+        yeelightRecord(record.txt ?? record.properties, ['id', 'mac', 'serial', 'model', 'modelid', 'md']);
+      const name = typeof record.name === 'string' ? record.name : '';
+      const model = typeof txt.model === 'string' ? txt.model : typeof txt.modelid === 'string' ? txt.modelid : '';
+      if (!name.toLowerCase().startsWith('yeelink-') && !/^YL[A-Z0-9]+$/i.test(model)) {
+        return unmatched('Generic Xiaomi mDNS does not establish a Yeelight device.');
+      }
+      let host: string | undefined;
+      const addresses = Array.isArray(record.addresses) ? record.addresses : [];
+      for (const candidate of [record.host, ...addresses]) {
+        try { host = yeelightAddress(candidate); break; } catch { continue; }
+      }
+      const id = txt.id === undefined ? undefined : yeelightId(txt.id);
+      return { matched: true, confidence: 'medium', reason: 'Unauthenticated Yeelight mDNS hint; vendor discovery must admit the exact ID.',
+        normalizedDeviceId: id, candidate: { source: 'mdns', integrationDomain: 'yeelight', id, host, name,
+          manufacturer: 'Yeelight', model: model || undefined, metadata: { discoveryHint: true } } };
+    } catch { return unmatched('Invalid Yeelight mDNS hint.'); }
   }
 }
 
 export class YeelightManualMatcher implements IDiscoveryMatcher<IYeelightManualEntry> {
-  public id = 'yeelight-manual-match';
-  public source = 'manual' as const;
-  public description = 'Recognize manual Yeelight setup entries by host or Yeelight metadata.';
+  public readonly id = 'yeelight-manual-match';
+  public readonly source = 'manual' as const;
+  public readonly description = 'Recognize explicitly selected local Yeelight endpoints.';
 
   public async matches(inputArg: IYeelightManualEntry): Promise<IDiscoveryMatch> {
-    const model = inputArg.model?.toLowerCase() || '';
-    const name = inputArg.name?.toLowerCase() || '';
-    const manufacturer = inputArg.manufacturer?.toLowerCase() || '';
-    const matched = Boolean(inputArg.host || inputArg.snapshot || inputArg.capabilities || inputArg.metadata?.yeelight || model.includes('yeelight') || name.includes('yeelight') || manufacturer === 'yeelight');
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'Manual entry does not contain Yeelight setup hints.' };
-    }
-    return {
-      matched: true,
-      confidence: inputArg.host ? 'high' : 'medium',
-      reason: 'Manual entry can start Yeelight setup.',
-      normalizedDeviceId: inputArg.id || inputArg.host,
-      candidate: {
-        source: 'manual',
-        integrationDomain: 'yeelight',
-        id: inputArg.id,
-        host: inputArg.host,
-        port: inputArg.port || defaultPort,
-        name: inputArg.name,
-        manufacturer: 'Yeelight',
-        model: inputArg.model,
-        metadata: {
-          ...inputArg.metadata,
-          properties: inputArg.properties,
-          capabilities: inputArg.capabilities,
-          snapshot: inputArg.snapshot,
-        },
-      },
-    };
+    try {
+      const input = yeelightRecord(inputArg, ['host', 'id', 'name', 'model', 'manufacturer']);
+      const host = yeelightAddress(input.host);
+      const id = yeelightId(input.id);
+      return { matched: true, confidence: 'medium', reason: 'Explicit setup hint; fresh targeted vendor discovery is required.', normalizedDeviceId: id,
+        candidate: { source: 'manual', integrationDomain: 'yeelight', host, id, manufacturer: 'Yeelight',
+          name: input.name === undefined ? undefined : yeelightText(input.name, 'name', 128),
+          model: input.model === undefined ? undefined : yeelightText(input.model, 'model', 128) } };
+    } catch { return unmatched('Manual Yeelight setup requires a local IPv4 endpoint and vendor ID.'); }
   }
 }
 
 export class YeelightCandidateValidator implements IDiscoveryValidator {
-  public id = 'yeelight-candidate-validator';
-  public description = 'Validate Yeelight candidates before starting local LAN setup.';
+  public readonly id = 'yeelight-candidate-validator';
+  public readonly description = 'Validate setup hints without authorizing network connection or controls.';
 
   public async validate(candidateArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
-    const manufacturer = candidateArg.manufacturer?.toLowerCase() || '';
-    const model = candidateArg.model?.toLowerCase() || '';
-    const name = candidateArg.name?.toLowerCase() || '';
-    const metadata = candidateArg.metadata || {};
-    const matched = candidateArg.integrationDomain === 'yeelight' || manufacturer === 'yeelight' || model.includes('yeelight') || name.includes('yeelight') || name.startsWith('yeelink-') || Boolean(metadata.capabilities || metadata.yeelight);
-    return {
-      matched,
-      confidence: matched && candidateArg.host ? 'high' : matched ? 'medium' : 'low',
-      reason: matched ? 'Candidate has Yeelight metadata.' : 'Candidate is not Yeelight.',
-      candidate: matched ? { ...candidateArg, port: candidateArg.port || defaultPort } : undefined,
-      normalizedDeviceId: candidateArg.id || candidateArg.host,
-    };
+    try {
+      if (candidateArg.integrationDomain !== 'yeelight') return unmatched('Candidate belongs to another integration.');
+      const id = yeelightId(candidateArg.id);
+      const host = yeelightAddress(candidateArg.host);
+      return { matched: true, confidence: 'medium', reason: 'Candidate can start setup; home scope and fresh vendor admission remain mandatory.',
+        normalizedDeviceId: id, candidate: { ...candidateArg, id, host } };
+    } catch { return unmatched('Yeelight setup candidate requires a local IPv4 endpoint and vendor ID.'); }
   }
 }
 
-export const createYeelightDiscoveryDescriptor = (): DiscoveryDescriptor => {
-  return new DiscoveryDescriptor({ integrationDomain: 'yeelight', displayName: 'Yeelight' })
-    .addMatcher(new YeelightSsdpMatcher())
-    .addMatcher(new YeelightMdnsMatcher())
-    .addMatcher(new YeelightManualMatcher())
-    .addValidator(new YeelightCandidateValidator());
-};
+export const createYeelightDiscoveryDescriptor = (): DiscoveryDescriptor =>
+  new DiscoveryDescriptor({ integrationDomain: 'yeelight', displayName: 'Yeelight' })
+    .addMatcher(new YeelightSsdpMatcher()).addMatcher(new YeelightMdnsMatcher())
+    .addMatcher(new YeelightManualMatcher()).addValidator(new YeelightCandidateValidator());