@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/kodi/kodi.types.ts

@@ -1,19 +1,42 @@
+import type * as plugins from '../../plugins.js';
+import type { INativeConfigFlowContext, INativeIntegrationSetupContext } from '../../core/types.js';
+
 export interface IKodiConfig {
-  host?: string;
-  port?: number;
-  wsPort?: number;
-  ssl?: boolean;
-  username?: string;
-  password?: string;
+  homeId: string;
+  origin: string;
+  expectedApplicationName: string;
+  expectedApplicationMajor: number;
+  /** Plain HTTP does not authenticate the selected server. */
+  allowUnencryptedHttp: true;
+  control?: { readonly trustSelectedEndpoint: true; readonly maximumVolume: number };
   timeoutMs?: number;
+  maxQueuedOperations?: number;
+  maxResponseBytes?: number;
   name?: string;
-  uniqueId?: string;
-  deviceInfo?: IKodiDeviceInfo;
-  snapshot?: IKodiSnapshot;
 }
 
 export interface IHomeAssistantKodiConfig extends IKodiConfig {}
 
+export interface IKodiClientOptions {
+  /** Caller-owned provider and secret storage; honor its cancellation signal. */
+  getBasicCredentials?: plugins.ecobridgeDeviceManager.IKodiProtocolOptions['getBasicCredentials'];
+}
+
+export interface IKodiIntegrationOptions extends Pick<IKodiClientOptions, 'getBasicCredentials'> {
+  homeId?: string;
+}
+
+/** Explicit selection by the embedding host; the string is not an authentication credential. */
+export interface IKodiSetupContext extends INativeIntegrationSetupContext {}
+
+export interface IKodiConfigFlowContext extends INativeConfigFlowContext {}
+
+export interface IKodiNativeSnapshot extends plugins.ecobridgeDeviceManager.IKodiSnapshot {
+  readonly homeId: string;
+  readonly name: string;
+  readonly online: true;
+}
+
 export interface IKodiDeviceInfo {
   id?: string;
   uuid?: string;
@@ -91,6 +114,7 @@ export interface IKodiMediaItem {
   [key: string]: unknown;
 }
 
+/** Pure imported data for offline conversion; never native runtime authority. */
 export interface IKodiSnapshot {
   deviceInfo: IKodiDeviceInfo;
   application?: IKodiApplicationProperties;
@@ -125,52 +149,3 @@ export interface IKodiManualEntry {
   manufacturer?: string;
   metadata?: Record<string, unknown>;
 }
-
-export type TKodiJsonRpcParams = Record<string, unknown> | unknown[] | undefined;
-
-export interface IKodiJsonRpcRequest {
-  jsonrpc: '2.0';
-  method: string;
-  params?: TKodiJsonRpcParams;
-  id: number;
-}
-
-export interface IKodiJsonRpcResponse<T = unknown> {
-  jsonrpc?: string;
-  result?: T;
-  error?: {
-    code?: number;
-    message?: string;
-    data?: unknown;
-  };
-  id?: number;
-}
-
-export type TKodiMediaType =
-  | 'album'
-  | 'artist'
-  | 'channel'
-  | 'directory'
-  | 'episode'
-  | 'file'
-  | 'movie'
-  | 'music'
-  | 'playlist'
-  | 'season'
-  | 'song'
-  | 'track'
-  | 'tvshow'
-  | 'url'
-  | 'video'
-  | string;
-
-export type TKodiInputCommand =
-  | 'up'
-  | 'down'
-  | 'left'
-  | 'right'
-  | 'select'
-  | 'back'
-  | 'home'
-  | 'info'
-  | string;

package/ts/integrations/kodi/kodi.validation.ts

@@ -0,0 +1,60 @@
+import type { IKodiConfig } from './kodi.types.js';
+
+export function kodiRecord(value: unknown, name: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError(`Kodi ${name} must be a plain data object.`);
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== 'string' || !descriptor || !('value' in descriptor) || !descriptor.enumerable) throw new TypeError(`Kodi ${name} cannot contain accessors, symbols or hidden fields.`);
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function kodiKeys(record: Record<string, unknown>, names: readonly string[]): void {
+  if (Object.keys(record).some((key) => !names.includes(key))) throw new TypeError('Kodi data contains unsupported fields.');
+}
+
+export function kodiText(value: unknown, name: string, maximum = 128): string {
+  if (typeof value !== 'string' || !value.trim() || value.length > maximum || /[\p{Cc}\p{Cs}]/u.test(value)) throw new TypeError(`Kodi ${name} must be nonempty bounded text without control characters.`);
+  return value;
+}
+
+export function kodiInteger(value: unknown, minimum: number, maximum: number, name: string): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new TypeError(`Kodi ${name} must be an integer from ${minimum} through ${maximum}.`);
+  return value;
+}
+
+export function kodiBoolean(value: unknown): boolean {
+  if (typeof value !== 'boolean') throw new TypeError('Kodi muted state requires an explicit boolean.');
+  return value;
+}
+
+/** Captures consumer data; the public foundation validates the selected origin. */
+export function normalizeKodiConfig(value: unknown): Readonly<IKodiConfig> {
+  const config = kodiRecord(value, 'configuration');
+  kodiKeys(config, ['homeId', 'origin', 'expectedApplicationName', 'expectedApplicationMajor', 'allowUnencryptedHttp', 'control', 'name', 'timeoutMs', 'maxQueuedOperations', 'maxResponseBytes']);
+  if (config.allowUnencryptedHttp !== true) throw new TypeError('Kodi requires explicit allowUnencryptedHttp: true acceptance.');
+  let control: IKodiConfig['control'];
+  if (config.control !== undefined) {
+    const value = kodiRecord(config.control, 'owner control policy');
+    kodiKeys(value, ['trustSelectedEndpoint', 'maximumVolume']);
+    if (value.trustSelectedEndpoint !== true) throw new TypeError('Kodi controls require explicit owner trust of the selected endpoint.');
+    control = Object.freeze({ trustSelectedEndpoint: true, maximumVolume: kodiInteger(value.maximumVolume, 0, 100, 'owner volume ceiling') });
+  }
+  return Object.freeze({
+    homeId: kodiText(config.homeId, 'home id', 256), origin: kodiText(config.origin, 'origin', 128),
+    expectedApplicationName: kodiText(config.expectedApplicationName, 'selected application name'),
+    expectedApplicationMajor: kodiInteger(config.expectedApplicationMajor, 0, 255, 'selected application major'),
+    allowUnencryptedHttp: true, control, name: config.name === undefined ? undefined : kodiText(config.name, 'display name'),
+    timeoutMs: kodiInteger(config.timeoutMs === undefined ? 5000 : config.timeoutMs, 1, 60000, 'deadline'),
+    maxQueuedOperations: kodiInteger(config.maxQueuedOperations === undefined ? 16 : config.maxQueuedOperations, 1, 128, 'operation capacity'),
+    maxResponseBytes: kodiInteger(config.maxResponseBytes === undefined ? 65536 : config.maxResponseBytes, 1024, 1048576, 'response bound'),
+  });
+}
+
+export function kodiSignal(value: unknown): AbortSignal | undefined {
+  if (value !== undefined && !(value instanceof AbortSignal)) throw new TypeError('Kodi cancellation requires an AbortSignal.');
+  return value;
+}

package/ts/integrations/lifx/lifx.classes.client.ts

@@ -1,9 +1,98 @@
-import { SimpleLocalClient } from '../../core/index.js';
-import type { ILifxConfig } from './lifx.types.js';
-import { lifxProfile } from './lifx.types.js';
+import * as plugins from '../../plugins.js';
+import type { ILifxColor, ILifxConfig, ILifxSnapshot } from './lifx.types.js';
+import { normalizeLifxConfig, readLifxColor } from './lifx.validation.js';
 
-export class LifxClient extends SimpleLocalClient<ILifxConfig> {
-  constructor(configArg: ILifxConfig) {
-    super(lifxProfile, configArg);
+export class LifxClient {
+  readonly #config: Readonly<ILifxConfig>;
+  readonly #protocol: plugins.ecobridgeDeviceManager.LifxProtocol;
+  readonly #lifetime = new AbortController();
+  readonly #operations = new Set<Promise<unknown>>();
+  readonly #parentSignal?: AbortSignal;
+  readonly #onParentAbort: () => void;
+  #healthy = false;
+  #closed = false;
+  #closePromise?: Promise<void>;
+
+  constructor(configArg: ILifxConfig, signalArg?: AbortSignal) {
+    this.#config = normalizeLifxConfig(configArg);
+    if (signalArg !== undefined && !(signalArg instanceof AbortSignal)) throw new TypeError('LIFX lifetime signal must be an AbortSignal.');
+    this.#protocol = new plugins.ecobridgeDeviceManager.LifxProtocol({
+      host: this.#config.host, macAddress: this.#config.macAddress, port: this.#config.port,
+      timeoutMs: this.#config.requestTimeoutMs, maxPendingOperations: this.#config.maxPendingOperations,
+    });
+    this.#parentSignal = signalArg;
+    this.#onParentAbort = () => { void this.destroy(); };
+    signalArg?.addEventListener('abort', this.#onParentAbort, { once: true });
+    if (signalArg?.aborted) this.#onParentAbort();
+  }
+
+  public isHealthy(): boolean { return this.#healthy && !this.#closed; }
+
+  public getSnapshot(signalArg?: AbortSignal): Promise<ILifxSnapshot> {
+    return this.#run(async (signal) => {
+      const info = await this.#protocol.getDeviceInfo({ signal });
+      const light = info.capabilities?.layout === 'single-zone' && info.capabilities.temperatureRange ?
+        await this.#protocol.getLightState({ signal }) : undefined;
+      const capabilities = info.capabilities && {
+        ...info.capabilities,
+        temperatureRange: info.capabilities.temperatureRange && [info.capabilities.temperatureRange[0], info.capabilities.temperatureRange[1]] as const,
+      };
+      signal.throwIfAborted();
+      return {
+        homeId: this.#config.homeId,
+        name: this.#config.name ?? (light?.label || capabilities?.name || `LIFX ${info.macAddress}`),
+        deviceInfo: { macAddress: info.macAddress, vendor: info.vendor, product: info.product,
+          firmware: { build: info.firmware.build.toString(), major: info.firmware.major, minor: info.firmware.minor }, capabilities },
+        lightState: light && { ...light }, online: true, observedAt: new Date().toISOString(),
+      };
+    }, signalArg);
+  }
+
+  public setPower(onArg: boolean, durationMsArg = 0, signalArg?: AbortSignal): Promise<plugins.ecobridgeDeviceManager.ILifxWriteResult> {
+    return this.#run((signal) => this.#protocol.setPower(onArg, { durationMs: durationMsArg, signal }), signalArg);
+  }
+
+  public setHsbk(colorArg: ILifxColor, durationMsArg = 0, signalArg?: AbortSignal): Promise<plugins.ecobridgeDeviceManager.ILifxWriteResult> {
+    const color = readLifxColor(colorArg);
+    return this.#run((signal) => this.#protocol.setHsbk(color, { durationMs: durationMsArg, signal }), signalArg);
+  }
+
+  public destroy(): Promise<void> {
+    if (this.#closePromise) return this.#closePromise;
+    this.#closed = true;
+    this.#healthy = false;
+    this.#parentSignal?.removeEventListener('abort', this.#onParentAbort);
+    this.#lifetime.abort(new Error('LIFX client is destroyed.'));
+    this.#closePromise = Promise.resolve().then(async () => {
+      const protocolClose = this.#protocol.close();
+      await Promise.allSettled([...this.#operations]);
+      await protocolClose;
+    });
+    return this.#closePromise;
+  }
+
+  #run<TResult>(workArg: (signalArg: AbortSignal) => Promise<TResult>, signalArg?: AbortSignal): Promise<TResult> {
+    if (this.#closed) return Promise.reject(new Error('LIFX client is destroyed.'));
+    if (signalArg !== undefined && !(signalArg instanceof AbortSignal)) return Promise.reject(new TypeError('LIFX operation signal must be an AbortSignal.'));
+    if (signalArg?.aborted) return Promise.reject(signalArg.reason);
+    const deadline = new AbortController();
+    const signal = AbortSignal.any([this.#lifetime.signal, deadline.signal, ...(signalArg ? [signalArg] : [])]);
+    const timer = setTimeout(() => deadline.abort(new Error('LIFX operation deadline exceeded.')), this.#config.requestTimeoutMs);
+    timer.unref();
+    const operation = Promise.resolve().then(() => {
+      signal.throwIfAborted();
+      return workArg(signal);
+    }).then((resultArg) => {
+      this.#healthy = !this.#closed && !signal.aborted;
+      return resultArg;
+    }, (errorArg: unknown) => {
+      this.#healthy = false;
+      throw errorArg;
+    }).finally(() => {
+      clearTimeout(timer);
+      this.#operations.delete(operation);
+    });
+    this.#operations.add(operation);
+    return operation;
   }
 }

package/ts/integrations/lifx/lifx.classes.configflow.ts

@@ -1,9 +1,36 @@
-import { SimpleLocalConfigFlow } from '../../core/index.js';
+import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { LifxClient } from './lifx.classes.client.js';
+import { createLifxDiscoveryDescriptor } from './lifx.discovery.js';
 import type { ILifxConfig } from './lifx.types.js';
-import { lifxProfile } from './lifx.types.js';
+import { assertLifxStoreScope, lifxKeys, lifxRecord, normalizeLifxConfig } from './lifx.validation.js';
 
-export class LifxConfigFlow extends SimpleLocalConfigFlow<ILifxConfig> {
-  constructor() {
-    super(lifxProfile);
+export class LifxConfigFlow implements IConfigFlow<ILifxConfig> {
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<ILifxConfig>> {
+    const matched = await createLifxDiscoveryDescriptor().getValidators()[0].validate(candidateArg, {});
+    if (!matched.matched || !matched.candidate) return { kind: 'error', error: matched.reason };
+    const candidate = matched.candidate;
+    return {
+      kind: 'form', title: 'Connect explicit LIFX LAN device',
+      description: 'Provide the authorized home and acknowledge the unauthenticated cleartext LAN protocol. The endpoint and MAC are fixed to this candidate.',
+      fields: [
+        { name: 'homeId', label: 'Home id', type: 'text', required: true },
+        { name: 'allowUnencryptedLan', label: 'Acknowledge unauthenticated cleartext LAN', type: 'boolean', required: true },
+        { name: 'name', label: 'Name', type: 'text' },
+      ],
+      submit: async (valuesArg) => {
+        let client: LifxClient | undefined;
+        try {
+          const values = lifxRecord(valuesArg, 'config flow values');
+          lifxKeys(values, ['homeId', 'allowUnencryptedLan', 'name', 'requestTimeoutMs', 'maxPendingOperations']);
+          const config = normalizeLifxConfig({ ...values, host: candidate.host, port: candidate.port, macAddress: candidate.macAddress });
+          assertLifxStoreScope(contextArg.configStore, config.homeId);
+          client = new LifxClient(config);
+          await client.getSnapshot();
+          return { kind: 'done', title: 'LIFX device validated', config };
+        } catch (errorArg) {
+          return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'LIFX setup validation failed.' };
+        } finally { await client?.destroy(); }
+      },
+    };
   }
 }

package/ts/integrations/lifx/lifx.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, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { LifxClient } from './lifx.classes.client.js';
 import { LifxConfigFlow } from './lifx.classes.configflow.js';
 import { createLifxDiscoveryDescriptor } from './lifx.discovery.js';
-import type { ILifxConfig } from './lifx.types.js';
-import { lifxDomain, lifxProfile } from './lifx.types.js';
+import { LifxMapper } from './lifx.mapper.js';
+import type { ILifxConfig, ILifxSnapshot } from './lifx.types.js';
+import { lifxProfile } from './lifx.types.js';
+import { assertLifxStoreScope, lifxInteger, lifxKeys, lifxRecord, normalizeLifxConfig, readLifxColor } from './lifx.validation.js';
 
-export class LifxIntegration extends SimpleLocalIntegration<ILifxConfig> {
-  public readonly domain = lifxDomain;
+export class LifxIntegration extends BaseIntegration<ILifxConfig> {
+  public readonly domain = 'lifx';
+  public readonly displayName = 'LIFX';
+  public readonly status = 'control-runtime' as const;
+  public readonly metadata = lifxProfile.metadata;
   public readonly discoveryDescriptor = createLifxDiscoveryDescriptor();
   public readonly configFlow = new LifxConfigFlow();
+  readonly #runtimes = new Set<LifxRuntime>();
+  readonly #pending = new Set<LifxClient>();
+  readonly #setups = new Set<Promise<IIntegrationRuntime>>();
+  #closed = false;
+  #closePromise?: Promise<void>;
 
-  constructor() {
-    super(lifxProfile);
+  public setup(configArg: ILifxConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    if (this.#closed) return Promise.reject(new Error('LIFX integration is destroyed.'));
+    const setup = this.#createRuntime(configArg, contextArg).finally(() => this.#setups.delete(setup));
+    this.#setups.add(setup);
+    return setup;
+  }
+
+  async #createRuntime(configArg: ILifxConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    const config = normalizeLifxConfig(configArg);
+    assertLifxStoreScope(contextArg.configStore, config.homeId);
+    const client = new LifxClient(config, contextArg.abortSignal);
+    this.#pending.add(client);
+    try {
+      const snapshot = await client.getSnapshot(contextArg.abortSignal);
+      if (this.#closed || contextArg.abortSignal?.aborted) throw new Error('LIFX setup was canceled.');
+      const runtime = new LifxRuntime(client, snapshot, () => this.#runtimes.delete(runtime));
+      this.#runtimes.add(runtime);
+      return runtime;
+    } catch (errorArg) {
+      await client.destroy();
+      throw errorArg;
+    } finally { this.#pending.delete(client); }
+  }
+
+  public destroy(): Promise<void> {
+    if (this.#closePromise) return this.#closePromise;
+    this.#closed = true;
+    this.#closePromise = Promise.resolve().then(async () => {
+      await Promise.all([
+        ...[...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()),
+        ...[...this.#pending].map((clientArg) => clientArg.destroy()),
+      ]);
+      await Promise.allSettled([...this.#setups]);
+    });
+    return this.#closePromise;
   }
 }
 
 export class HomeAssistantLifxIntegration extends LifxIntegration {}
+
+class LifxRuntime implements IIntegrationRuntime {
+  public readonly domain = 'lifx';
+  readonly #deviceId: string;
+  readonly #entityId: string;
+  readonly #hasLight: boolean;
+  #closePromise?: Promise<void>;
+
+  constructor(private readonly client: LifxClient, identityArg: ILifxSnapshot, private readonly released: () => void) {
+    this.#deviceId = LifxMapper.deviceId(identityArg);
+    this.#entityId = LifxMapper.lightEntityId(identityArg);
+    this.#hasLight = identityArg.lightState !== undefined;
+  }
+
+  public isHealthy(): boolean { return this.client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return LifxMapper.toDevices(await this.client.getSnapshot(signalArg));
+  }
+  public async entities(): Promise<IIntegrationEntity[]> { return LifxMapper.toEntities(await this.client.getSnapshot()); }
+
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    try {
+      const request = lifxRecord(requestArg, 'service request');
+      lifxKeys(request, ['domain', 'service', 'target', 'data']);
+      if (typeof request.domain !== 'string' || typeof request.service !== 'string') throw new TypeError('LIFX service domain and service must be strings.');
+      this.#assertTarget(request.target);
+      const data = request.data === undefined ? {} : lifxRecord(request.data, 'service data');
+      if (request.domain === 'lifx' && ['status', 'snapshot', 'refresh'].includes(request.service)) {
+        lifxKeys(data, []);
+        return { success: true, data: await this.client.getSnapshot() };
+      }
+      if (request.domain === 'light' && ['turn_on', 'turn_off'].includes(request.service)) {
+        lifxKeys(data, ['durationMs']);
+        const duration = lifxInteger(data.durationMs === undefined ? 0 : data.durationMs, 0, 60000, 'durationMs');
+        return accepted(await this.client.setPower(request.service === 'turn_on', duration));
+      }
+      if (request.domain === 'lifx' && request.service === 'set_hsbk') {
+        lifxKeys(data, ['hue', 'saturation', 'brightness', 'kelvin', 'durationMs']);
+        const color = readLifxColor({ hue: data.hue, saturation: data.saturation, brightness: data.brightness, kelvin: data.kelvin });
+        const duration = lifxInteger(data.durationMs === undefined ? 0 : data.durationMs, 0, 60000, 'durationMs');
+        return accepted(await this.client.setHsbk(color, duration));
+      }
+      throw new TypeError('LIFX service is unsupported.');
+    } catch (errorArg) { return failed(errorArg); }
+  }
+
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const request = lifxRecord(requestArg, 'feature write');
+      lifxKeys(request, ['device', 'feature', 'value']);
+      const device = lifxRecord(request.device, 'feature device');
+      const feature = lifxRecord(request.feature, 'feature');
+      if (device.id !== this.#deviceId || device.integrationDomain !== this.domain) throw new TypeError('LIFX feature device is not owned by this home runtime.');
+      if (feature.id === 'power') {
+        if (typeof request.value !== 'boolean') throw new TypeError('LIFX power feature requires a boolean.');
+        return accepted(await this.client.setPower(request.value, 0, signalArg));
+      }
+      if (feature.id === 'hsbk') return accepted(await this.client.setHsbk(readLifxColor(request.value), 0, signalArg));
+      throw new TypeError('LIFX feature is not writable.');
+    } catch (errorArg) { return failed(errorArg); }
+  }
+
+  public destroy(): Promise<void> {
+    this.#closePromise ??= this.client.destroy().then(() => { this.released(); });
+    return this.#closePromise;
+  }
+
+  #assertTarget(valueArg: unknown): void {
+    const target = lifxRecord(valueArg, 'service target');
+    lifxKeys(target, ['deviceId', 'entityId']);
+    if (target.deviceId === undefined && target.entityId === undefined ||
+      target.deviceId !== undefined && target.deviceId !== this.#deviceId ||
+      target.entityId !== undefined && (target.entityId !== this.#entityId || !this.#hasLight)) {
+      throw new TypeError('LIFX services require one exact owned device or light entity target.');
+    }
+  }
+}
+
+function accepted(resultArg: plugins.ecobridgeDeviceManager.ILifxWriteResult): IServiceCallResult {
+  return { success: true, data: { effectOutcome: resultArg.outcome, observedState: { ...resultArg.observedState }, physicalCompletion: 'unconfirmed' } };
+}
+function failed(errorArg: unknown): IServiceCallResult {
+  return {
+    success: false,
+    error: errorArg instanceof Error ? errorArg.message : 'LIFX operation failed.',
+    data: { effectOutcome: errorArg instanceof plugins.ecobridgeDeviceManager.LifxProtocolError ? errorArg.effectOutcome : 'not-sent',
+      code: errorArg instanceof plugins.ecobridgeDeviceManager.LifxProtocolError ? errorArg.code : 'INVALID_OPERATION' },
+  };
+}

package/ts/integrations/lifx/lifx.discovery.ts

@@ -1,4 +1,27 @@
-import { createSimpleLocalDiscoveryDescriptor } from '../../core/index.js';
-import { lifxProfile } from './lifx.types.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IDiscoveryCandidate, IDiscoveryMatch } from '../../core/types.js';
+import { lifxName, lifxRecord, readLifxEndpoint } from './lifx.validation.js';
 
-export const createLifxDiscoveryDescriptor = () => createSimpleLocalDiscoveryDescriptor(lifxProfile);
+function matchCandidate(valueArg: unknown): IDiscoveryMatch {
+  try {
+    const input = lifxRecord(valueArg, 'discovery candidate');
+    if (input.source !== 'manual' && input.source !== 'custom' || input.integrationDomain !== 'lifx') {
+      return { matched: false, confidence: 'low', reason: 'An explicit manual/custom LIFX candidate is required.' };
+    }
+    const endpoint = readLifxEndpoint(input.host, input.macAddress, input.port);
+    const candidate: IDiscoveryCandidate = {
+      source: input.source === 'manual' ? 'manual' : 'custom', integrationDomain: 'lifx', ...endpoint,
+      name: input.name === undefined ? undefined : lifxName(input.name, 'candidate name'),
+    };
+    return { matched: true, confidence: 'medium', reason: 'Explicit LIFX endpoint/MAC binding; live identity is checked during setup.', candidate };
+  } catch (errorArg) {
+    return { matched: false, confidence: 'low', reason: errorArg instanceof Error ? errorArg.message : 'Invalid LIFX endpoint candidate.' };
+  }
+}
+
+export function createLifxDiscoveryDescriptor(): DiscoveryDescriptor {
+  return new DiscoveryDescriptor({ integrationDomain: 'lifx', displayName: 'LIFX' })
+    .addMatcher({ id: 'lifx-manual-match', source: 'manual', matches: async (inputArg) => matchCandidate(inputArg) })
+    .addMatcher({ id: 'lifx-custom-match', source: 'custom', matches: async (inputArg) => matchCandidate(inputArg) })
+    .addValidator({ id: 'lifx-explicit-endpoint', validate: async (candidateArg) => matchCandidate(candidateArg) });
+}

package/ts/integrations/lifx/lifx.mapper.ts

@@ -1,26 +1,54 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
-import { SimpleLocalMapper, type IIntegrationEntity, type ISimpleLocalSnapshot, type ISimpleLocalSnapshotOptions, type TSimpleLocalRawData } from '../../core/index.js';
-import type { ILifxConfig } from './lifx.types.js';
-import { lifxProfile } from './lifx.types.js';
+import type * as plugins from '../../plugins.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import type { ILifxSnapshot } from './lifx.types.js';
 
 export class LifxMapper {
-  public static toSnapshot(optionsArg: Omit<ISimpleLocalSnapshotOptions<ILifxConfig>, 'profile'>): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ ...optionsArg, profile: lifxProfile });
+  public static deviceId(snapshotArg: Pick<ILifxSnapshot, 'homeId' | 'deviceInfo'>): string {
+    return `lifx:${encodeURIComponent(snapshotArg.homeId)}:${snapshotArg.deviceInfo.macAddress}`;
   }
-
-  public static toSnapshotFromRaw(configArg: ILifxConfig, rawDataArg: TSimpleLocalRawData): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ profile: lifxProfile, config: configArg, rawData: rawDataArg, online: true, source: 'manual' });
-  }
-
-  public static toDevices(snapshotArg: ISimpleLocalSnapshot): shxInterfaces.data.IDeviceDefinition[] {
-    return SimpleLocalMapper.toDevices(lifxProfile, snapshotArg);
+  public static lightEntityId(snapshotArg: Pick<ILifxSnapshot, 'homeId' | 'deviceInfo'>): string {
+    return `${this.deviceId(snapshotArg)}:light`;
   }
 
-  public static toEntities(snapshotArg: ISimpleLocalSnapshot): IIntegrationEntity[] {
-    return SimpleLocalMapper.toEntities(lifxProfile, snapshotArg);
+  public static toDevices(snapshotArg: ILifxSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    const info = snapshotArg.deviceInfo;
+    const light = snapshotArg.lightState;
+    const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
+      { id: 'connectivity', capability: 'sensor', name: 'Connectivity', readable: true, writable: false },
+      { id: 'product', capability: 'sensor', name: 'Product', readable: true, writable: false },
+      { id: 'firmware', capability: 'sensor', name: 'Firmware', readable: true, writable: false },
+    ];
+    const state: plugins.shxInterfaces.data.IDeviceState[] = [
+      { featureId: 'connectivity', value: 'online', updatedAt: snapshotArg.observedAt },
+      { featureId: 'product', value: info.product, updatedAt: snapshotArg.observedAt },
+      { featureId: 'firmware', value: `${info.firmware.major}.${info.firmware.minor}`, updatedAt: snapshotArg.observedAt },
+    ];
+    if (light) {
+      const singleZone = info.capabilities?.layout === 'single-zone' && info.capabilities.temperatureRange !== undefined;
+      features.push({ id: 'power', capability: 'light', name: 'Power', readable: true, writable: singleZone });
+      state.push({ featureId: 'power', value: light.power > 0, updatedAt: snapshotArg.observedAt });
+      features.push({ id: 'hsbk', capability: 'light', name: 'HSBK (exact uint16 units)', readable: true, writable: singleZone && info.capabilities?.color === true });
+      state.push({ featureId: 'hsbk', value: { hue: light.hue, saturation: light.saturation, brightness: light.brightness, kelvin: light.kelvin }, updatedAt: snapshotArg.observedAt });
+    }
+    return [{
+      id: this.deviceId(snapshotArg), integrationDomain: 'lifx', name: snapshotArg.name,
+      manufacturer: info.vendor === 1 ? 'LIFX' : undefined,
+      model: info.capabilities?.name, protocol: 'udp', online: snapshotArg.online,
+      features, state,
+      metadata: { homeId: snapshotArg.homeId, macAddress: info.macAddress, vendor: info.vendor, product: info.product,
+        firmwareBuild: info.firmware.build, capabilities: info.capabilities, lanAuthenticated: false },
+    }];
   }
 
-  public static slug(valueArg: unknown): string {
-    return SimpleLocalMapper.slug(valueArg);
+  public static toEntities(snapshotArg: ILifxSnapshot): IIntegrationEntity[] {
+    const light = snapshotArg.lightState;
+    if (!light) return [];
+    return [{
+      id: this.lightEntityId(snapshotArg), uniqueId: this.lightEntityId(snapshotArg), deviceId: this.deviceId(snapshotArg),
+      integrationDomain: 'lifx', platform: 'light', name: snapshotArg.name, state: light.power > 0 ? 'on' : 'off',
+      available: snapshotArg.online,
+      attributes: { hue: light.hue, saturation: light.saturation, brightness: light.brightness, kelvin: light.kelvin,
+        rawPower: light.power, observedAt: snapshotArg.observedAt, capabilities: snapshotArg.deviceInfo.capabilities },
+    }];
   }
 }