@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/wled/wled.classes.configflow.ts

@@ -1,9 +1,30 @@
-import { SimpleLocalConfigFlow } from '../../core/index.js';
+import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { WledClient } from './wled.classes.client.js';
+import { wledPlainFields } from './wled.commands.js';
+import { WledCandidateValidator } from './wled.discovery.js';
+import { wledConfig } from './wled.validation.js';
 import type { IWledConfig } from './wled.types.js';
-import { wledProfile } from './wled.types.js';
 
-export class WledConfigFlow extends SimpleLocalConfigFlow<IWledConfig> {
-  constructor() {
-    super(wledProfile);
+export class WledConfigFlow implements IConfigFlow<IWledConfig> {
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IWledConfig>> {
+    void contextArg;
+    const admitted = await new WledCandidateValidator().validate(candidateArg);
+    const endpoint = admitted.candidate;
+    if (!endpoint) return { kind: 'error', error: 'WLED config flow requires an admitted WLED manual or mDNS endpoint.' };
+    return {
+      kind: 'form', title: 'Connect WLED', description: 'Validate the controller HTTP endpoint and pin its returned MAC identity. WLED has no API authentication or native TLS.',
+      fields: [{ name: 'host', label: 'Host', type: 'text', required: true }, { name: 'port', label: 'Port', type: 'number' }, { name: 'expectedMac', label: 'Expected MAC', type: 'text' }],
+      submit: async (valuesArg) => {
+        if (!wledPlainFields(valuesArg, ['host', 'port', 'expectedMac'])) return { kind: 'error', error: 'WLED config contains unsupported settings.' };
+        let client: WledClient | undefined;
+        try {
+          const config = wledConfig({ host: valuesArg.host === undefined ? endpoint.host : valuesArg.host, port: valuesArg.port === undefined ? endpoint.port : valuesArg.port, expectedMac: valuesArg.expectedMac === undefined ? endpoint.macAddress : valuesArg.expectedMac });
+          client = new WledClient(config);
+          const snapshot = await client.getSnapshot();
+          return { kind: 'done', title: 'WLED configured', config: { ...config, expectedMac: snapshot.info.mac } };
+        } catch { return { kind: 'error', error: 'Could not validate the WLED endpoint or MAC identity.' }; }
+        finally { await client?.destroy(); }
+      },
+    };
   }
 }

package/ts/integrations/wled/wled.classes.integration.ts

@@ -1,17 +1,152 @@
-import { SimpleLocalIntegration } from '../../core/index.js';
+import * as plugins from '../../plugins.js';
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { WledClient } from './wled.classes.client.js';
 import { WledConfigFlow } from './wled.classes.configflow.js';
+import { wledPlainFields, validateWledChange } from './wled.commands.js';
 import { createWledDiscoveryDescriptor } from './wled.discovery.js';
-import type { IWledConfig } from './wled.types.js';
-import { wledDomain, wledProfile } from './wled.types.js';
+import { WledMapper } from './wled.mapper.js';
+import type { IWledConfig, IWledSnapshot, IWledStateChange } from './wled.types.js';
+import { wledProfile } from './wled.types.js';
+import { WledWriteError } from './wled.errors.js';
 
-export class WledIntegration extends SimpleLocalIntegration<IWledConfig> {
-  public readonly domain = wledDomain;
+export class WledIntegration extends BaseIntegration<IWledConfig> {
+  public readonly domain = 'wled';
+  public readonly displayName = 'WLED';
+  public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createWledDiscoveryDescriptor();
   public readonly configFlow = new WledConfigFlow();
+  public readonly metadata = wledProfile.metadata;
+  private readonly runtimes = new Set<WledRuntime>();
+  private readonly pendingClients = new Set<WledClient>();
+  private destroyed = false;
 
-  constructor() {
-    super(wledProfile);
+  public async setup(configArg: IWledConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    if (this.destroyed) throw new Error('WLED integration has been destroyed.');
+    const client = new WledClient(configArg, contextArg.abortSignal, contextArg.logger);
+    this.pendingClients.add(client);
+    try {
+      const snapshot = await client.getSnapshot();
+      if (this.destroyed) throw new Error('WLED integration has been destroyed.');
+      const runtime = new WledRuntime(client, snapshot, () => this.runtimes.delete(runtime));
+      this.runtimes.add(runtime);
+      this.pendingClients.delete(client);
+      return runtime;
+    } catch (errorArg) {
+      await client.destroy();
+      this.pendingClients.delete(client);
+      throw errorArg;
+    }
+  }
+
+  public async destroy(): Promise<void> {
+    this.destroyed = true;
+    await Promise.all([...this.runtimes].map((runtimeArg) => runtimeArg.destroy()).concat([...this.pendingClients].map(async (clientArg) => {
+      await clientArg.destroy();
+      this.pendingClients.delete(clientArg);
+    })));
   }
 }
 
 export class HomeAssistantWledIntegration extends WledIntegration {}
+
+class WledRuntime implements IIntegrationRuntime {
+  public readonly domain = 'wled';
+
+  constructor(private readonly client: WledClient, private snapshot: IWledSnapshot, private readonly onDestroyed: () => void) {}
+
+  public isHealthy(): boolean { return this.client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.snapshot = await this.client.getSnapshot(signalArg);
+    return WledMapper.toDevices(this.snapshot, this.isHealthy());
+  }
+  public async entities(): Promise<IIntegrationEntity[]> {
+    this.snapshot = await this.client.getSnapshot();
+    return WledMapper.toEntities(this.snapshot, this.isHealthy());
+  }
+
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    let previous = WledMapper.toEntities(this.snapshot);
+    return this.client.subscribe((eventArg) => {
+      const emit = (event: Omit<IIntegrationEvent, 'integrationDomain' | 'deviceId' | 'timestamp'>): void => handlerArg({
+        ...event, integrationDomain: this.domain, deviceId: WledMapper.deviceId(this.snapshot), timestamp: Date.now(),
+      });
+      if (eventArg.type === 'snapshot') {
+        this.snapshot = eventArg.snapshot;
+        const current = WledMapper.toEntities(this.snapshot, true);
+        for (const entity of current) {
+          const old = previous.find((entryArg) => entryArg.id === entity.id);
+          if (JSON.stringify(old) !== JSON.stringify(entity)) emit({ type: old ? 'state_changed' : 'entity_added', entityId: entity.id, data: { entity } });
+        }
+        for (const entity of previous) if (!current.some((entryArg) => entryArg.id === entity.id)) emit({ type: 'entity_removed', entityId: entity.id });
+        previous = current;
+      } else if (eventArg.type === 'availability') emit({ type: 'availability_changed', data: { available: eventArg.available } });
+      else emit({ type: 'error', data: { message: eventArg.error.message } });
+    }, signalArg);
+  }
+
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    try {
+      if (!wledPlainFields(requestArg, ['domain', 'service', 'target', 'data']) || !wledPlainFields(requestArg.target, ['deviceId', 'entityId'])) throw new Error('WLED requires a plain service request and exact target.');
+      if (requestArg.domain !== 'light' || !['turn_on', 'turn_off', 'set_level', 'set_color'].includes(requestArg.service)) throw new Error('WLED supports light.turn_on, turn_off, set_level and set_color.');
+      const segmentId = this.targetSegment(requestArg.target);
+      const fields = requestArg.service === 'turn_off' ? [] : requestArg.service === 'set_level' ? ['brightness'] : requestArg.service === 'set_color' ? ['rgb_color', 'white'] : ['brightness', 'rgb_color', 'white'];
+      const data = requestArg.data ?? {};
+      if (!wledPlainFields(data, fields) || Object.values(data).some((valueArg) => valueArg === undefined)) throw new Error('WLED service contains unsupported or undefined data.');
+      if (requestArg.service === 'set_level' && data.brightness === undefined || requestArg.service === 'set_color' && data.rgb_color === undefined && data.white === undefined) throw new Error('WLED service requires an explicit value.');
+      const change = validateWledChange({
+        on: requestArg.service === 'turn_on' ? true : requestArg.service === 'turn_off' ? false : undefined,
+        brightness: data.brightness, rgb: data.rgb_color, white: data.white,
+      });
+      this.snapshot = await this.client.setState(segmentId, change);
+      return { success: true, data: structuredClone(this.snapshot) };
+    } catch (errorArg) { return this.failure(errorArg); }
+  }
+
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      if (!wledPlainFields(requestArg, ['device', 'feature', 'value'], ['device', 'feature', 'value']) ||
+        !wledPlainFields(requestArg.device, ['id', 'integrationDomain', 'name', 'room', 'protocol', 'manufacturer', 'model', 'online', 'features', 'state', 'metadata'], ['id', 'integrationDomain']) ||
+        !wledPlainFields(requestArg.feature, ['id', 'capability', 'name', 'readable', 'writable', 'unit'], ['id'])) throw new Error('WLED feature writes require a plain request, device, feature and own value without accessors.');
+      if (requestArg.device.id !== WledMapper.deviceId(this.snapshot) || requestArg.device.integrationDomain !== this.domain) throw new Error('WLED feature target does not belong to this controller.');
+      const device = WledMapper.toDevices(this.snapshot)[0];
+      const feature = device.features.find((entryArg) => entryArg.id === requestArg.feature.id);
+      if (!feature?.writable) throw new Error('WLED feature is not a writable capability of this controller.');
+      const segment = /^segment_(\d+)_(power|brightness|rgb|white)$/.exec(feature.id);
+      const key = segment?.[2] ?? feature.id;
+      const change: IWledStateChange = {};
+      if (key === 'power') {
+        if (typeof requestArg.value !== 'boolean') throw new Error('WLED power requires a boolean.');
+        change.on = requestArg.value;
+      } else if (key === 'brightness' || key === 'white') {
+        if (typeof requestArg.value !== 'number') throw new Error('WLED brightness and white require integer values.');
+        change[key] = requestArg.value;
+      } else if (key === 'rgb') {
+        if (typeof requestArg.value !== 'string' || !/^#[a-f\d]{6}$/i.test(requestArg.value)) throw new Error('WLED RGB feature requires #rrggbb.');
+        const value = requestArg.value;
+        change.rgb = [Number.parseInt(value.slice(1, 3), 16), Number.parseInt(value.slice(3, 5), 16), Number.parseInt(value.slice(5, 7), 16)];
+      } else throw new Error('WLED feature is not supported.');
+      this.snapshot = await this.client.setState(segment ? Number(segment[1]) : undefined, change, signalArg);
+      return { success: true, data: structuredClone(this.snapshot) };
+    } catch (errorArg) { return this.failure(errorArg); }
+  }
+
+  public async destroy(): Promise<void> { await this.client.destroy(); this.onDestroyed(); }
+
+  private targetSegment(targetArg: { entityId?: string; deviceId?: string }): number | undefined {
+    const deviceId = WledMapper.deviceId(this.snapshot);
+    if (targetArg.deviceId !== undefined && targetArg.deviceId !== deviceId) throw new Error('WLED device target does not belong to this controller.');
+    if (targetArg.entityId === undefined) {
+      if (targetArg.deviceId !== deviceId) throw new Error('WLED requires an exact controller or segment target.');
+      return undefined;
+    }
+    if (targetArg.entityId === WledMapper.entityId(this.snapshot)) return undefined;
+    const segment = this.snapshot.state.seg.find((entryArg) => WledMapper.entityId(this.snapshot, entryArg.id) === targetArg.entityId);
+    if (!segment) throw new Error('WLED entity target does not belong to an active segment of this controller.');
+    return segment.id;
+  }
+
+  private failure(errorArg: unknown): IServiceCallResult {
+    return { success: false, error: errorArg instanceof Error ? errorArg.message : 'WLED operation failed.', data: { effectOutcome: errorArg instanceof WledWriteError ? errorArg.effectOutcome : 'not-sent' } };
+  }
+}

package/ts/integrations/wled/wled.classes.subscription.ts

@@ -0,0 +1,122 @@
+import * as plugins from '../../plugins.js';
+import { DeviceCommunicationError } from '../../core/errors.js';
+import { parseWledSnapshot } from './wled.validation.js';
+import type { IWledSnapshot } from './wled.types.js';
+
+interface IWledSubscriptionOptions {
+  url: URL;
+  mac: string;
+  timeoutMs: number;
+  signal: AbortSignal;
+  onSnapshot(snapshotArg: IWledSnapshot): void;
+  onAvailability(availableArg: boolean): void;
+  onError(errorArg: Error): void;
+}
+
+export class WledSubscription {
+  private socket?: plugins.ws.WebSocket;
+  private starting?: Promise<void>;
+  private resolveStart?: () => void;
+  private rejectStart?: (errorArg: Error) => void;
+  private closing?: Promise<void>;
+  private resolveClose?: () => void;
+  private deadline?: ReturnType<typeof setTimeout>;
+  private stopping = false;
+  private closed = false;
+  private healthy = false;
+
+  constructor(private readonly options: IWledSubscriptionOptions) {}
+
+  public get isHealthy(): boolean { return this.healthy && !this.stopping; }
+  public get isClosed(): boolean { return this.closed; }
+  public get isStopping(): boolean { return this.stopping; }
+
+  public start(): Promise<void> {
+    if (this.starting) return this.starting;
+    if (this.stopping || this.options.signal.aborted) return Promise.reject(new DOMException('WLED subscription cancelled.', 'AbortError'));
+    this.starting = new Promise<void>((resolveArg, rejectArg) => { this.resolveStart = resolveArg; this.rejectStart = rejectArg; });
+    this.closing = new Promise<void>((resolveArg) => { this.resolveClose = resolveArg; });
+    this.options.signal.addEventListener('abort', this.handleAbort, { once: true });
+    this.deadline = setTimeout(() => this.fail(new DeviceCommunicationError('WLED websocket initial state timed out.')), this.options.timeoutMs);
+    try {
+      this.socket = new plugins.ws.WebSocket(this.options.url, { handshakeTimeout: this.options.timeoutMs, followRedirects: false, perMessageDeflate: false, maxPayload: 1024 * 1024 });
+      this.socket.on('message', this.handleMessage);
+      this.socket.on('error', this.handleError);
+      this.socket.on('close', this.handleClose);
+    } catch {
+      this.fail(new DeviceCommunicationError('WLED websocket connection failed.'));
+      this.finishClose();
+    }
+    return this.starting;
+  }
+
+  public async stop(): Promise<void> {
+    this.stopping = true;
+    this.setHealthy(false);
+    clearTimeout(this.deadline);
+    this.rejectStart?.(new DOMException('WLED subscription cancelled.', 'AbortError'));
+    this.rejectStart = undefined;
+    this.resolveStart = undefined;
+    if (!this.socket || this.closed) { this.finishClose(); return; }
+    // This receive-only socket owns no outstanding command acknowledgement to preserve.
+    this.socket.terminate();
+    await this.closing;
+  }
+
+  private readonly handleMessage = (dataArg: plugins.ws.RawData, binaryArg: boolean): void => {
+    if (this.stopping) return;
+    try {
+      if (binaryArg) throw new DeviceCommunicationError('WLED returned an unexpected binary websocket message.');
+      const data = Array.isArray(dataArg) ? Buffer.concat(dataArg) : dataArg instanceof ArrayBuffer ? Buffer.from(new Uint8Array(dataArg)) : dataArg;
+      const value: unknown = JSON.parse(data.toString('utf8'));
+      const snapshot = parseWledSnapshot(value, this.options.mac);
+      this.options.onSnapshot(snapshot);
+      clearTimeout(this.deadline);
+      this.setHealthy(true);
+      this.resolveStart?.();
+      this.resolveStart = undefined;
+      this.rejectStart = undefined;
+    } catch (errorArg) {
+      this.fail(errorArg instanceof DeviceCommunicationError ? errorArg : new DeviceCommunicationError('WLED returned invalid websocket JSON.'));
+    }
+  };
+
+  private readonly handleError = (): void => {
+    if (!this.stopping) this.fail(new DeviceCommunicationError('WLED websocket connection failed.'));
+  };
+
+  private readonly handleClose = (): void => {
+    if (!this.stopping) this.fail(new DeviceCommunicationError('WLED websocket connection closed.'));
+    this.finishClose();
+  };
+
+  private readonly handleAbort = (): void => { void this.stop(); };
+
+  private fail(errorArg: Error): void {
+    this.setHealthy(false);
+    clearTimeout(this.deadline);
+    this.rejectStart?.(errorArg);
+    this.rejectStart = undefined;
+    this.resolveStart = undefined;
+    this.options.onError(errorArg);
+    void this.stop();
+  }
+
+  private setHealthy(valueArg: boolean): void {
+    if (this.healthy === valueArg) return;
+    this.healthy = valueArg;
+    this.options.onAvailability(valueArg);
+  }
+
+  private finishClose(): void {
+    if (this.closed) return;
+    this.closed = true;
+    clearTimeout(this.deadline);
+    this.options.signal.removeEventListener('abort', this.handleAbort);
+    this.socket?.removeListener('message', this.handleMessage);
+    this.socket?.removeListener('error', this.handleError);
+    this.socket?.removeListener('close', this.handleClose);
+    this.resolveClose?.();
+    this.resolveClose = undefined;
+  }
+}

package/ts/integrations/wled/wled.commands.ts

@@ -0,0 +1,54 @@
+import type { IWledSnapshot, IWledStateChange } from './wled.types.js';
+import { isWledRecord, wledInteger } from './wled.validation.js';
+
+export const wledPlainFields = (valueArg: unknown, fieldsArg: string[], requiredFieldsArg: string[] = []): valueArg is Record<string, unknown> => {
+  if (!isWledRecord(valueArg) || Object.getPrototypeOf(valueArg) !== Object.prototype) return false;
+  const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+  return Reflect.ownKeys(valueArg).every((keyArg) => typeof keyArg === 'string' && fieldsArg.includes(keyArg) && 'value' in descriptors[keyArg]) &&
+    requiredFieldsArg.every((keyArg) => descriptors[keyArg] !== undefined && 'value' in descriptors[keyArg]);
+};
+
+const wledRgb = (valueArg: unknown): [number, number, number] => {
+  const invalid = (): never => { throw new Error('WLED RGB requires three own integer color channels between 0 and 255.'); };
+  if (!Array.isArray(valueArg) || valueArg.length !== 3) return invalid();
+  const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+  if (Reflect.ownKeys(valueArg).some((keyArg) => typeof keyArg !== 'string' || !['0', '1', '2', 'length'].includes(keyArg) || !('value' in descriptors[keyArg]))) return invalid();
+  const channel = (indexArg: string): number => {
+    const descriptor = descriptors[indexArg];
+    const value: unknown = descriptor?.value;
+    if (!descriptor || !('value' in descriptor) || !wledInteger(value, 0, 255)) return invalid();
+    return value;
+  };
+  return [channel('0'), channel('1'), channel('2')];
+};
+
+export const validateWledChange = (valueArg: unknown): IWledStateChange => {
+  if (!wledPlainFields(valueArg, ['on', 'brightness', 'rgb', 'white']) || Object.keys(valueArg).length === 0) throw new Error('WLED state changes require explicit supported values.');
+  if (valueArg.on !== undefined && typeof valueArg.on !== 'boolean' || valueArg.brightness !== undefined && !wledInteger(valueArg.brightness, 1, 255) || valueArg.white !== undefined && !wledInteger(valueArg.white, 0, 255)) throw new Error('WLED requires boolean power and bounded integer brightness or white values.');
+  let rgb: [number, number, number] | undefined;
+  if (valueArg.rgb !== undefined) rgb = wledRgb(valueArg.rgb);
+  const change: IWledStateChange = { on: valueArg.on, brightness: valueArg.brightness, rgb, white: valueArg.white };
+  if (Object.values(change).every((entryArg) => entryArg === undefined)) throw new Error('WLED state changes must contain a value.');
+  return change;
+};
+
+export const wledPayload = (snapshotArg: IWledSnapshot, segmentIdArg: number | undefined, changeArg: IWledStateChange): Record<string, unknown> => {
+  const payload: Record<string, unknown> = {};
+  if (changeArg.on !== undefined) payload.on = changeArg.on;
+  if (changeArg.brightness !== undefined) payload.bri = changeArg.brightness;
+  if (segmentIdArg === undefined) {
+    if (changeArg.rgb !== undefined || changeArg.white !== undefined) throw new Error('WLED color writes require an exact segment target.');
+    return { ...payload, udpn: { nn: true } };
+  }
+  const segment = snapshotArg.state.seg.find((entryArg) => entryArg.id === segmentIdArg);
+  if (!segment) throw new Error('WLED target segment is not active on the connected controller.');
+  const capabilities = snapshotArg.info.leds.seglc?.[segmentIdArg] ?? 0;
+  if (changeArg.rgb !== undefined && !(capabilities & 1) || changeArg.white !== undefined && (!(capabilities & 2) || segment.col[0].length !== 4)) throw new Error('WLED segment does not advertise the requested color capability.');
+  if (changeArg.rgb !== undefined || changeArg.white !== undefined) {
+    const color = [...segment.col[0]];
+    if (changeArg.rgb !== undefined) color.splice(0, 3, ...changeArg.rgb);
+    if (changeArg.white !== undefined) color[3] = changeArg.white;
+    payload.col = [color];
+  }
+  return { seg: [{ id: segmentIdArg, ...payload }], udpn: { nn: true } };
+};

package/ts/integrations/wled/wled.discovery.ts

@@ -1,4 +1,53 @@
-import { createSimpleLocalDiscoveryDescriptor } from '../../core/index.js';
-import { wledProfile } from './wled.types.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
+import { isWledRecord, normalizeWledMac, wledConfig } from './wled.validation.js';
 
-export const createWledDiscoveryDescriptor = () => createSimpleLocalDiscoveryDescriptor(wledProfile);
+const unmatched = (): IDiscoveryMatch => ({ matched: false, confidence: 'low', reason: 'Record is not an explicit WLED endpoint or official WLED mDNS advertisement.' });
+
+const plainRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  isWledRecord(valueArg) && Object.getPrototypeOf(valueArg) === Object.prototype && Reflect.ownKeys(valueArg).every((keyArg) => typeof keyArg === 'string' && 'value' in Object.getOwnPropertyDescriptor(valueArg, keyArg)!);
+
+const candidate = (valueArg: unknown, sourceArg: 'manual' | 'mdns'): IDiscoveryMatch => {
+  if (!plainRecord(valueArg) || valueArg.integrationDomain !== undefined && valueArg.integrationDomain !== 'wled') return unmatched();
+  if (sourceArg === 'manual' && valueArg.integrationDomain !== 'wled') return unmatched();
+  let expectedMac: string | undefined;
+  if (sourceArg === 'mdns') {
+    if (typeof valueArg.type !== 'string' || !/^_wled\._tcp(?:\.local)?\.?$/i.test(valueArg.type) || !plainRecord(valueArg.txt)) return unmatched();
+    try { expectedMac = normalizeWledMac(valueArg.txt.mac); } catch { return unmatched(); }
+  } else if (valueArg.macAddress !== undefined) {
+    try { expectedMac = normalizeWledMac(valueArg.macAddress); } catch { return unmatched(); }
+  }
+  try {
+    const config = wledConfig({ host: valueArg.host, port: valueArg.port, expectedMac });
+    const result: IDiscoveryCandidate = { source: sourceArg, integrationDomain: 'wled', host: config.host, port: config.port, macAddress: expectedMac, manufacturer: 'WLED' };
+    // Discovery data is untrusted; no arbitrary metadata becomes connection settings.
+    return { matched: true, confidence: 'high', reason: 'WLED endpoint admitted; setup will verify its JSON API and MAC.', candidate: result, normalizedDeviceId: expectedMac ? `wled.device.${expectedMac}` : undefined };
+  } catch { return unmatched(); }
+};
+
+export class WledManualMatcher implements IDiscoveryMatcher {
+  public readonly id = 'wled-manual-match';
+  public readonly source = 'manual' as const;
+  public async matches(valueArg: unknown): Promise<IDiscoveryMatch> { return candidate(valueArg, 'manual'); }
+}
+
+export class WledMdnsMatcher implements IDiscoveryMatcher {
+  public readonly id = 'wled-mdns-match';
+  public readonly source = 'mdns' as const;
+  public async matches(valueArg: unknown): Promise<IDiscoveryMatch> { return candidate(valueArg, 'mdns'); }
+}
+
+export class WledCandidateValidator implements IDiscoveryValidator {
+  public readonly id = 'wled-candidate-validator';
+  public async validate(valueArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
+    if (!plainRecord(valueArg) || valueArg.source !== 'manual' && valueArg.source !== 'mdns' || valueArg.integrationDomain !== 'wled') return unmatched();
+    if (valueArg.source === 'mdns') {
+      try { normalizeWledMac(valueArg.macAddress); } catch { return unmatched(); }
+    }
+    const result = candidate(valueArg, 'manual');
+    return result.candidate ? { ...result, candidate: { ...result.candidate, source: valueArg.source === 'mdns' ? 'mdns' : 'manual' } } : result;
+  }
+}
+
+export const createWledDiscoveryDescriptor = (): DiscoveryDescriptor => new DiscoveryDescriptor({ integrationDomain: 'wled', displayName: 'WLED' })
+  .addMatcher(new WledManualMatcher()).addMatcher(new WledMdnsMatcher()).addValidator(new WledCandidateValidator());

package/ts/integrations/wled/wled.errors.ts

@@ -0,0 +1,9 @@
+import { DeviceCommunicationError } from '../../core/errors.js';
+
+export class WledWriteError extends DeviceCommunicationError {
+  public readonly effectOutcome = 'indeterminate';
+  constructor(errorArg: Error) {
+    super(`${errorArg.message} An unconfirmed WLED write must not be retried automatically.`);
+    this.name = errorArg.name === 'AbortError' ? 'AbortError' : 'WledWriteError';
+  }
+}

package/ts/integrations/wled/wled.mapper.ts

@@ -1,26 +1,46 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
-import { SimpleLocalMapper, type IIntegrationEntity, type ISimpleLocalSnapshot, type ISimpleLocalSnapshotOptions, type TSimpleLocalRawData } from '../../core/index.js';
-import type { IWledConfig } from './wled.types.js';
-import { wledProfile } from './wled.types.js';
+import * as plugins from '../../plugins.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import { parseWledSnapshot } from './wled.validation.js';
+import type { IWledSnapshot } from './wled.types.js';
 
 export class WledMapper {
-  public static toSnapshot(optionsArg: Omit<ISimpleLocalSnapshotOptions<IWledConfig>, 'profile'>): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ ...optionsArg, profile: wledProfile });
-  }
-
-  public static toSnapshotFromRaw(configArg: IWledConfig, rawDataArg: TSimpleLocalRawData): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ profile: wledProfile, config: configArg, rawData: rawDataArg, online: true, source: 'manual' });
-  }
-
-  public static toDevices(snapshotArg: ISimpleLocalSnapshot): shxInterfaces.data.IDeviceDefinition[] {
-    return SimpleLocalMapper.toDevices(wledProfile, snapshotArg);
-  }
+  public static toSnapshotFromRaw(valueArg: unknown): IWledSnapshot { return parseWledSnapshot(valueArg); }
+  public static deviceId(snapshotArg: IWledSnapshot): string { return `wled.device.${snapshotArg.info.mac}`; }
+  public static entityId(snapshotArg: IWledSnapshot, segmentIdArg?: number): string { return `light.wled_${snapshotArg.info.mac}${segmentIdArg === undefined ? '' : `_segment_${segmentIdArg}`}`; }
 
-  public static toEntities(snapshotArg: ISimpleLocalSnapshot): IIntegrationEntity[] {
-    return SimpleLocalMapper.toEntities(wledProfile, snapshotArg);
+  public static toDevices(snapshotArg: IWledSnapshot, availableArg = true): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    const features: plugins.shxInterfaces.data.IDeviceFeature[] = [];
+    const state: plugins.shxInterfaces.data.IDeviceState[] = [];
+    const add = (idArg: string, nameArg: string, valueArg: plugins.shxInterfaces.data.TDeviceStateValue, writableArg = true): void => {
+      features.push({ id: idArg, name: nameArg, capability: writableArg ? 'light' : 'sensor', readable: true, writable: writableArg });
+      state.push({ featureId: idArg, value: valueArg, updatedAt: snapshotArg.updatedAt });
+    };
+    add('power', 'Controller power', snapshotArg.state.on);
+    add('brightness', 'Controller brightness', snapshotArg.state.bri);
+    add('firmware', 'Firmware', snapshotArg.info.ver, false);
+    add('connectivity', 'Connectivity', availableArg ? 'online' : 'offline', false);
+    for (const segment of snapshotArg.state.seg) {
+      const prefix = `segment_${segment.id}`;
+      const name = segment.n || `Segment ${segment.id}`;
+      const capabilities = snapshotArg.info.leds.seglc?.[segment.id] ?? 0;
+      add(`${prefix}_power`, `${name} power`, segment.on);
+      add(`${prefix}_brightness`, `${name} brightness`, segment.bri);
+      if (capabilities & 1) add(`${prefix}_rgb`, `${name} RGB`, `#${segment.col[0].slice(0, 3).map((channelArg) => channelArg.toString(16).padStart(2, '0')).join('')}`);
+      if (capabilities & 2 && segment.col[0].length === 4) add(`${prefix}_white`, `${name} white channel`, segment.col[0][3]);
+    }
+    return [{ id: this.deviceId(snapshotArg), integrationDomain: 'wled', name: snapshotArg.info.name, protocol: 'http', manufacturer: 'WLED', model: snapshotArg.info.product,
+      online: availableArg, features, state, metadata: { macAddress: snapshotArg.info.mac, firmware: snapshotArg.info.ver, ledCount: snapshotArg.info.leds.count } }];
   }
 
-  public static slug(valueArg: unknown): string {
-    return SimpleLocalMapper.slug(valueArg);
+  public static toEntities(snapshotArg: IWledSnapshot, availableArg = true): IIntegrationEntity[] {
+    const deviceId = this.deviceId(snapshotArg);
+    const create = (segmentIdArg?: number): IIntegrationEntity => {
+      const segment = segmentIdArg === undefined ? undefined : snapshotArg.state.seg.find((entryArg) => entryArg.id === segmentIdArg);
+      return { id: this.entityId(snapshotArg, segmentIdArg), uniqueId: this.entityId(snapshotArg, segmentIdArg), integrationDomain: 'wled', deviceId, platform: 'light',
+        name: segment ? segment.n || `Segment ${segment.id}` : snapshotArg.info.name,
+        state: snapshotArg.state.on && (segment?.on ?? true) ? 'on' : 'off', available: availableArg,
+        attributes: segment ? { segmentId: segment.id, segmentPower: segment.on, brightness: segment.bri, primaryColor: [...segment.col[0]], capabilities: snapshotArg.info.leds.seglc?.[segment.id] ?? 0 } : { brightness: snapshotArg.state.bri } };
+    };
+    return [create(), ...snapshotArg.state.seg.map((segmentArg) => create(segmentArg.id))];
   }
 }