@smarthome.exchange/integrations 0.1.0 → 1.0.0

package/ts/integrations/hue/hue.mapper.ts

@@ -4,78 +4,46 @@ import type { IHueEvent, IHueResourceResponse } from './hue.types.js';
 
 export class HueMapper {
   public static toDevices(resourcesArg: IHueResourceResponse): plugins.shxInterfaces.data.IDeviceDefinition[] {
-    const devices: plugins.shxInterfaces.data.IDeviceDefinition[] = [];
-
-    if (resourcesArg.bridge) {
-      devices.push({
-        id: `hue.bridge.${resourcesArg.bridge.id}`,
-        integrationDomain: 'hue',
-        name: resourcesArg.bridge.metadata?.name || 'Hue Bridge',
-        protocol: 'hue',
-        manufacturer: resourcesArg.bridge.productData?.manufacturerName || 'Signify',
-        model: resourcesArg.bridge.productData?.productName || resourcesArg.bridge.productData?.modelId,
-        online: true,
-        features: [
-          { id: 'connectivity', capability: 'sensor', name: 'Connectivity', readable: true, writable: false },
-        ],
-        state: [
-          { featureId: 'connectivity', value: 'online', updatedAt: new Date().toISOString() },
-        ],
-      });
-    }
-
+    const timestamp = new Date().toISOString();
+    const devices: plugins.shxInterfaces.data.IDeviceDefinition[] = [{
+      id: `hue.bridge.${resourcesArg.bridge.id}`,
+      integrationDomain: 'hue', name: resourcesArg.bridge.metadata?.name || 'Hue Bridge', protocol: 'hue',
+      manufacturer: resourcesArg.bridge.productData?.manufacturerName,
+      model: resourcesArg.bridge.productData?.productName || resourcesArg.bridge.productData?.modelId,
+      online: true,
+      features: [{ id: 'connectivity', capability: 'sensor', name: 'Connectivity', readable: true, writable: false }],
+      state: [{ featureId: 'connectivity', value: 'online', updatedAt: timestamp }],
+    }];
     for (const light of resourcesArg.lights) {
+      const owner = resourcesArg.devices.find((deviceArg) => deviceArg.id === light.owner.rid);
       devices.push({
-        id: `hue.light.${light.id}`,
-        integrationDomain: 'hue',
-        name: light.metadata?.name || `Hue Light ${light.id}`,
-        protocol: 'hue',
-        manufacturer: 'Signify',
-        model: light.metadata?.archetype,
-        online: true,
-        features: [
-          { id: 'on', capability: 'light', name: 'Power', readable: true, writable: true },
-          { id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: true, unit: '%' },
-        ],
-        state: [
-          { featureId: 'on', value: light.on?.on ?? false, updatedAt: new Date().toISOString() },
-          { featureId: 'brightness', value: light.dimming?.brightness ?? null, updatedAt: new Date().toISOString() },
-        ],
-        metadata: {
-          hueOwnerRid: light.owner?.rid,
-        },
+        id: `hue.light.${light.id}`, integrationDomain: 'hue',
+        name: light.metadata?.name || owner?.metadata?.name || `Hue Light ${light.id}`, protocol: 'hue',
+        manufacturer: owner?.productData?.manufacturerName,
+        model: owner?.productData?.productName || owner?.productData?.modelId,
+        online: light.available,
+        features: [{ id: 'on', capability: 'light', name: 'Power', readable: true, writable: true },
+          ...(light.dimming ? [{ id: 'brightness', capability: 'light' as const, name: 'Brightness', readable: true, writable: true, unit: '%' }] : [])],
+        state: [{ featureId: 'on', value: light.on.on, updatedAt: timestamp },
+          ...(light.dimming ? [{ featureId: 'brightness', value: light.dimming.brightness, updatedAt: timestamp }] : [])],
+        metadata: { hueOwnerRid: light.owner.rid },
       });
     }
-
     return devices;
   }
 
   public static toEntities(resourcesArg: IHueResourceResponse): IIntegrationEntity[] {
     return resourcesArg.lights.map((lightArg) => ({
-      id: `light.${this.slug(lightArg.metadata?.name || lightArg.id)}`,
-      uniqueId: `hue_light_${lightArg.id}`,
-      integrationDomain: 'hue',
-      deviceId: `hue.light.${lightArg.id}`,
-      platform: 'light',
-      name: lightArg.metadata?.name || `Hue Light ${lightArg.id}`,
-      state: lightArg.on?.on ? 'on' : 'off',
-      attributes: {
-        brightness: lightArg.dimming?.brightness,
-      },
-      available: true,
+      id: `light.${lightArg.id}`, uniqueId: `hue_light_${lightArg.id}`, integrationDomain: 'hue',
+      deviceId: `hue.light.${lightArg.id}`, platform: 'light',
+      name: lightArg.metadata?.name || resourcesArg.devices.find((deviceArg) => deviceArg.id === lightArg.owner.rid)?.metadata?.name || `Hue Light ${lightArg.id}`,
+      state: lightArg.on.on ? 'on' : 'off',
+      attributes: lightArg.dimming ? { brightness: lightArg.dimming.brightness } : {}, available: lightArg.available,
     }));
   }
 
   public static toIntegrationEvent(eventArg: IHueEvent): IIntegrationEvent {
-    return {
-      type: 'state_changed',
-      integrationDomain: 'hue',
-      data: eventArg,
-      timestamp: Date.now(),
-    };
-  }
-
-  private static slug(valueArg: string) {
-    return valueArg.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'hue_light';
+    return { type: eventArg.type === 'delete' ? 'device_removed' : eventArg.type === 'add' ? 'device_added' : 'state_changed',
+      integrationDomain: 'hue', data: eventArg, timestamp: Date.now() };
   }
 }

package/ts/integrations/hue/hue.types.ts

@@ -3,11 +3,14 @@ export interface IHueConfig {
   host: string;
   appKey: string;
   port?: number;
-  resources?: IHueResourceResponse;
+  /** PEM CA supplied by the operator from a trusted source. */
+  trustedCa?: string;
+  requestTimeoutMs?: number;
 }
 
 export interface IHueLightStatePatch {
   on?: boolean;
+  /** Hue v2 brightness is a percentage, from 0 through 100. */
   brightness?: number;
 }
 
@@ -29,24 +32,15 @@ export interface IHueDeviceResource {
 export interface IHueLightResource {
   id: string;
   idV1?: string;
-  owner?: {
-    rid: string;
-    rtype: string;
-  };
-  metadata?: {
-    name?: string;
-    archetype?: string;
-  };
-  on?: {
-    on: boolean;
-  };
-  dimming?: {
-    brightness: number;
-  };
+  owner: { rid: string; rtype: 'device' };
+  metadata?: { name?: string; archetype?: string };
+  on: { on: boolean };
+  dimming?: { brightness: number };
+  available: boolean;
 }
 
 export interface IHueResourceResponse {
-  bridge?: IHueDeviceResource;
+  bridge: IHueDeviceResource;
   devices: IHueDeviceResource[];
   lights: IHueLightResource[];
 }
@@ -63,6 +57,6 @@ export interface IHueMdnsRecord {
 
 export interface IHueEvent {
   id: string;
-  type: string;
-  data: unknown;
+  type: 'add' | 'update' | 'delete';
+  data: Array<{ id: string; type: string }>;
 }

package/ts/integrations/hue/hue.validation.ts

@@ -0,0 +1,154 @@
+import * as plugins from '../../plugins.js';
+import type { IHueConfig, IHueDeviceResource, IHueEvent, IHueLightResource, IHueLightStatePatch, IHueResourceResponse } from './hue.types.js';
+
+export const hueContentType = (valueArg: unknown, expectedArg: string): boolean =>
+  typeof valueArg === 'string' && valueArg.split(';', 1)[0].trim().toLowerCase() === expectedArg;
+
+export const hueUuid = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(valueArg);
+
+export const hueBridgeId = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[0-9a-f]{16}$/i.test(valueArg);
+
+export const hueRecord = (valueArg: unknown): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+    throw new Error('Hue returned an invalid object.');
+  }
+  return valueArg as Record<string, unknown>;
+};
+
+export const normalizeHueHost = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string' || valueArg.length > 253 || valueArg !== valueArg.trim()) {
+    throw new Error('Hue host must be a hostname or IP address.');
+  }
+  const host = valueArg.replace(/^\[([^\]]+)\]$/, '$1');
+  if (plugins.net.isIP(host)) return host;
+  if (!/^(?=.{1,253}$)[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/i.test(host)
+    || host.split('.').some((partArg) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(partArg))) {
+    throw new Error('Hue host must be a hostname or IP address.');
+  }
+  return host;
+};
+
+export const normalizeHueConfig = (configArg: IHueConfig): Required<Pick<IHueConfig, 'bridgeId' | 'host' | 'appKey' | 'port' | 'requestTimeoutMs'>> & Pick<IHueConfig, 'trustedCa'> => {
+  const record = hueRecord(configArg);
+  const allowed = new Set(['bridgeId', 'host', 'appKey', 'port', 'trustedCa', 'requestTimeoutMs']);
+  if (Reflect.ownKeys(record).some((keyArg) => typeof keyArg !== 'string' || !allowed.has(keyArg))) {
+    throw new Error('Hue configuration contains unsupported fields.');
+  }
+  if (!hueBridgeId(record.bridgeId)) throw new Error('Hue bridgeId must contain 16 hexadecimal characters.');
+  if (typeof record.appKey !== 'string' || !/^[a-z0-9_-]{1,256}$/i.test(record.appKey)) {
+    throw new Error('Hue appKey must be a nonempty application key.');
+  }
+  const port = record.port ?? 443;
+  const requestTimeoutMs = record.requestTimeoutMs ?? 10_000;
+  if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535) throw new Error('Hue port is invalid.');
+  if (typeof requestTimeoutMs !== 'number' || !Number.isInteger(requestTimeoutMs) || requestTimeoutMs < 50 || requestTimeoutMs > 60_000) {
+    throw new Error('Hue requestTimeoutMs must be between 50 and 60000.');
+  }
+  if (record.trustedCa !== undefined && (typeof record.trustedCa !== 'string' || record.trustedCa.length > 65_536
+    || !record.trustedCa.includes('-----BEGIN CERTIFICATE-----'))) throw new Error('Hue trustedCa must contain a PEM certificate.');
+  return { bridgeId: record.bridgeId.toLowerCase(), host: normalizeHueHost(record.host), appKey: record.appKey, port, requestTimeoutMs,
+    trustedCa: typeof record.trustedCa === 'string' ? record.trustedCa : undefined };
+};
+
+export const validateHuePatch = (patchArg: IHueLightStatePatch): void => {
+  const patch = hueRecord(patchArg);
+  if (Reflect.ownKeys(patch).some((keyArg) => keyArg !== 'on' && keyArg !== 'brightness')
+    || (patch.on === undefined && patch.brightness === undefined)) throw new Error('Hue light state requires power or brightness.');
+  if (patch.on !== undefined && typeof patch.on !== 'boolean') throw new Error('Hue power must be boolean.');
+  if (patch.brightness !== undefined && (typeof patch.brightness !== 'number' || !Number.isFinite(patch.brightness)
+    || patch.brightness < 0 || patch.brightness > 100)) throw new Error('Hue brightness must be between 0 and 100 percent.');
+};
+
+export const parseHueEnvelope = (valueArg: unknown): unknown[] => {
+  const envelope = hueRecord(valueArg);
+  if (!Array.isArray(envelope.errors) || !Array.isArray(envelope.data) || envelope.data.length > 10_000) {
+    throw new Error('Hue returned an invalid API envelope.');
+  }
+  if (envelope.errors.length) throw new Error('Hue bridge rejected the API request.');
+  return envelope.data;
+};
+
+const optionalString = (valueArg: unknown): string | undefined => {
+  if (valueArg === undefined) return undefined;
+  if (typeof valueArg !== 'string' || valueArg.length > 1024) throw new Error('Hue returned an invalid text field.');
+  return valueArg;
+};
+
+const deviceResource = (resourceArg: Record<string, unknown>): IHueDeviceResource => {
+  if (!hueUuid(resourceArg.id)) throw new Error('Hue device resource has an invalid UUID.');
+  const metadata = resourceArg.metadata === undefined ? undefined : hueRecord(resourceArg.metadata);
+  const product = resourceArg.product_data === undefined ? undefined : hueRecord(resourceArg.product_data);
+  return { id: resourceArg.id.toLowerCase(), idV1: optionalString(resourceArg.id_v1),
+    metadata: metadata ? { name: optionalString(metadata.name), archetype: optionalString(metadata.archetype) } : undefined,
+    productData: product ? { manufacturerName: optionalString(product.manufacturer_name), modelId: optionalString(product.model_id),
+      productName: optionalString(product.product_name), softwareVersion: optionalString(product.software_version) } : undefined };
+};
+
+export const parseHueResources = (dataArg: unknown[], bridgeIdArg: string): IHueResourceResponse => {
+  const devices = new Map<string, IHueDeviceResource>();
+  const connectivity = new Map<string, boolean>();
+  const lightResources: Record<string, unknown>[] = [];
+  const ids = new Set<string>();
+  let bridgeOwner: string | undefined;
+  for (const item of dataArg) {
+    const resource = hueRecord(item);
+    if (!hueUuid(resource.id) || typeof resource.type !== 'string' || resource.type.length > 64 || ids.has(resource.id.toLowerCase())) {
+      throw new Error('Hue returned invalid or duplicate resource identities.');
+    }
+    ids.add(resource.id.toLowerCase());
+    if (resource.type === 'device') devices.set(resource.id.toLowerCase(), deviceResource(resource));
+    if (resource.type === 'light') lightResources.push(resource);
+    if (resource.type === 'bridge') {
+      if (bridgeOwner || typeof resource.bridge_id !== 'string' || resource.bridge_id.toLowerCase() !== bridgeIdArg) {
+        throw new Error('Hue bridge identity does not match the configured bridge.');
+      }
+      const owner = hueRecord(resource.owner);
+      if (!hueUuid(owner.rid) || owner.rtype !== 'device') throw new Error('Hue bridge owner is invalid.');
+      bridgeOwner = owner.rid.toLowerCase();
+    }
+    if (resource.type === 'zigbee_connectivity') {
+      const owner = hueRecord(resource.owner);
+      if (!hueUuid(owner.rid) || owner.rtype !== 'device' || typeof resource.status !== 'string'
+        || !['connected', 'disconnected', 'connectivity_issue', 'unidirectional_incoming', 'pending_discovery'].includes(resource.status)
+        || connectivity.has(owner.rid.toLowerCase())) throw new Error('Hue connectivity resource is invalid.');
+      connectivity.set(owner.rid.toLowerCase(), resource.status === 'connected');
+    }
+  }
+  const bridge = bridgeOwner ? devices.get(bridgeOwner) : undefined;
+  if (!bridge) throw new Error('Hue response has no verified bridge device.');
+  const lights: IHueLightResource[] = lightResources.map((resourceArg) => {
+    const owner = hueRecord(resourceArg.owner);
+    const power = hueRecord(resourceArg.on);
+    const dimming = resourceArg.dimming === undefined ? undefined : hueRecord(resourceArg.dimming);
+    const metadata = resourceArg.metadata === undefined ? undefined : hueRecord(resourceArg.metadata);
+    if (!hueUuid(owner.rid) || owner.rtype !== 'device' || !devices.has(owner.rid.toLowerCase()) || typeof power.on !== 'boolean') {
+      throw new Error('Hue light owner or power state is invalid.');
+    }
+    if (dimming && (typeof dimming.brightness !== 'number' || !Number.isFinite(dimming.brightness)
+      || dimming.brightness < 0 || dimming.brightness > 100)) throw new Error('Hue light brightness is invalid.');
+    return { id: (resourceArg.id as string).toLowerCase(), idV1: optionalString(resourceArg.id_v1), owner: { rid: owner.rid.toLowerCase(), rtype: 'device' },
+      metadata: metadata ? { name: optionalString(metadata.name), archetype: optionalString(metadata.archetype) } : undefined,
+      on: { on: power.on }, dimming: dimming ? { brightness: dimming.brightness as number } : undefined,
+      available: connectivity.get(owner.rid.toLowerCase()) === true };
+  });
+  return { bridge, devices: [...devices.values()], lights };
+};
+
+export const parseHueEvents = (valueArg: unknown): IHueEvent[] => {
+  if (!Array.isArray(valueArg) || valueArg.length > 256) throw new Error('Hue event batch is invalid.');
+  return valueArg.map((itemArg: unknown) => {
+    const event = hueRecord(itemArg);
+    if (!hueUuid(event.id) || !['add', 'update', 'delete'].includes(String(event.type))
+      || !Array.isArray(event.data) || event.data.length > 10_000) throw new Error('Hue event envelope is invalid.');
+    const data: IHueEvent['data'] = [];
+    for (const resourceArg of event.data) {
+      const resource = hueRecord(resourceArg);
+      if (!hueUuid(resource.id) || typeof resource.type !== 'string') throw new Error('Hue event resource identity is invalid.');
+      // Notifications cause authoritative rereads; unknown resource payloads may contain credentials.
+      if (['bridge', 'device', 'light', 'zigbee_connectivity'].includes(resource.type)) data.push({ id: resource.id.toLowerCase(), type: resource.type });
+    }
+    return { id: event.id.toLowerCase(), type: event.type as IHueEvent['type'], data };
+  }).filter((eventArg) => eventArg.data.length > 0);
+};

package/ts/integrations/hue/readme.md

@@ -0,0 +1,71 @@
+# Philips Hue integration
+
+Native TypeScript integration for Philips Hue API v2 bridges. It discovers bridge candidates, verifies a configured bridge over HTTPS, reads authoritative devices and light state, controls power and supported brightness, and receives local change notifications through the bridge event stream.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Configuration and TLS
+
+`IHueConfig` requires `bridgeId` (the bridge's 16-character hexadecimal ID), `host` (an IP address or hostname), and `appKey`. Optional fields are `port` (443 by default), `trustedCa` (a PEM CA certificate), and `requestTimeoutMs` (10000 by default, permitted range 50–60000).
+
+Create an application key using the bridge's physical link button and the [Hue developer setup procedure](https://developers.meethue.com/develop/get-started-2/). This integration accepts that key; it does not generate or print credentials. Its config flow verifies a live resource read before returning a completed configuration. The application key travels only in the `hue-application-key` request header. Inject the host's encrypted `IConfigStore` into the normal integration setup flow when storing the resulting configuration.
+
+Certificate-chain verification remains enabled. The certificate must identify the configured bridge ID, even when the connection uses an IP address. Hue bridges using the Signify private CA require the operator to supply the appropriate trusted CA from the [Hue HTTPS guidance](https://developers.meethue.com/develop/application-design-guidance/using-https/). The system trust store is used when `trustedCa` is absent. No trust-on-first-use, HTTP downgrade, disabled verification or caller-supplied resource snapshots are supported. Discovery metadata does not establish a trusted bridge identity.
+
+Use `HueIntegration` from `@smarthome.exchange/integrations` with operator-supplied configuration:
+
+```typescript
+const integration = new HueIntegration();
+const runtime = await integration.setup({ bridgeId, host, appKey, trustedCa }, { configStore });
+try {
+  const lights = (await runtime.devices()).filter((device) => device.id.startsWith('hue.light.'));
+  console.log(lights.map((device) => ({ id: device.id, name: device.name, online: device.online })));
+} finally {
+  await integration.destroy();
+}
+```
+
+## Reads and controls
+
+Setup checks both the TLS identity and the `bridge_id` returned by `/clip/v2/resource`. Device/light IDs are validated UUIDs. Entities use `light.<resource UUID>` and devices use `hue.light.<resource UUID>`; changing a display name preserves identity. This replaces the previous display-name entity IDs. The `resources` configuration fixture field has been removed.
+
+Lights advertise brightness only when the bridge reports the `dimming` capability. Availability follows the owning device's Zigbee connectivity resource; missing or disconnected connectivity is unavailable. Manufacturer and model come from the owning device, including supported third-party Hue lights.
+
+Light services are `turn_on`, `turn_off` and `set_percentage`. `turn_on` accepts optional `brightness` from 0 to 100; `set_percentage` requires `percentage` in that same range. A target must match the current entity/device exactly; supplying both requires them to identify the same light. `writeFeature` supports boolean `on` and numeric `brightness` only for an available light's declared writable capabilities. Unsupported fields, unknown targets and values outside the protocol range are rejected.
+
+Writes use `PUT /clip/v2/resource/light/<UUID>` and require the bridge's matching resource acknowledgement. Success means the bridge accepted the write; it does not guarantee physical delivery. Accepted writes never change local read state. Each `devices()` or `entities()` call reads current authoritative resources, and writes are not automatically retried.
+
+## Notifications and ownership
+
+`subscribe()` opens authenticated HTTPS `/eventstream/clip/v2` and returns an asynchronous, idempotent unsubscribe function. Change notifications contain only relevant resource IDs/types; consumers reread authoritative state. Unknown resource payloads are omitted because they may contain credentials. Invalid frames, stream termination and transport failures produce an error event and mark the runtime unhealthy. Reads do not silently restart a failed subscription; the host may explicitly establish a new one or replace the runtime.
+
+Requests have whole-response deadlines and a 4 MiB body limit. Discovery uses the fixed documented `https://discovery.meethue.com/` broker with a five-second deadline and 256 KiB body limit. SSE frames are limited to 1 MiB and batches to 256 events. A client permits at most 32 outstanding connections, two event subscriptions, and three simultaneous HTTPS sockets. Caller cancellation and `destroy()` close owned requests/streams; destroy waits for them to close. The integration also owns pending setups and destroys their clients on failure or shutdown.
+
+## Verification and limits
+
+Tests use disposable CA-signed local TLS bridges, including untrusted issuers, a wrong bridge certificate, resource identity mismatch, exact PUT payloads, non-optimistic reads, unsupported controls, unavailable devices, malformed/oversized bodies, cancellation and event-stream cleanup. No physical bridge or owner's home was accessed.
+
+The public [Hue API announcement](https://developers.meethue.com/new-hue-api/) establishes API v2 HTTPS, local proactive events and the supported discovery methods. Detailed Hue API and HTTPS pages require a developer login and returned login/403 here. Implemented wire resource models and event paths were cross-checked against [aiohue's upstream v2 implementation](https://github.com/home-assistant-libs/aiohue/tree/main/aiohue/v2). Aiohue's disabled-TLS and geofence keepalive workaround are not used. Physical bridge firmware compatibility, operator CA provisioning and physical command delivery remain acceptance checks. Color, color temperature, scenes, entertainment streaming, grouped lights and accessory sensors are not exposed by this runtime.
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/integrations/index.ts

@@ -210,8 +210,8 @@ export * from './hisense_aehw4a1/index.js';
 export * from './hitron_coda/index.js';
 export * from './hlk_sw16/index.js';
 export * from './holiday/index.js';
-export * from './homee/index.js';
 export * from './homeassistant/index.js';
+export * from './homee/index.js';
 export * from './homekit/index.js';
 export * from './homekit_controller/index.js';
 export * from './homematic/index.js';
@@ -415,12 +415,14 @@ export * from './soundtouch/index.js';
 export * from './squeezebox/index.js';
 export * from './synology_dsm/index.js';
 export * from './synology_srm/index.js';
+export * from './tasmota/index.js';
 export * from './tomato/index.js';
 export * from './tplink/index.js';
 export * from './tplink_lte/index.js';
 export * from './tplink_omada/index.js';
 export * from './tradfri/index.js';
 export * from './transmission/index.js';
+export * from './tuya/index.js';
 export * from './twinkly/index.js';
 export * from './ubus/index.js';
 export * from './unifi/index.js';
@@ -458,3 +460,5 @@ export * from './zha/index.js';
 export * from './ziggo_mediabox_xl/index.js';
 export * from './zoneminder/index.js';
 export * from './zwave_js/index.js';
+
+export * from './zigbee2mqtt/index.js';

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(); }
+      },
+    };
   }
 }