@smarthome.exchange/integrations 0.1.0 → 1.0.0

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))];
   }
 }

package/ts/integrations/wled/wled.types.ts

@@ -1,93 +1,65 @@
-import type { ISimpleLocalConfig, ISimpleLocalIntegrationProfile, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/index.js';
+export const wledDomain = 'wled';
+export const wledDefaultName = 'WLED';
 
-export const wledDomain = "wled";
-export const wledDefaultName = "WLED";
+export interface IWledConfig {
+  host: string;
+  port?: number;
+  expectedMac?: string;
+  requestTimeoutMs?: number;
+}
 
-export type TWledRawData = TSimpleLocalRawData;
-export interface IWledSnapshot extends ISimpleLocalSnapshot {}
-export interface IWledConfig extends ISimpleLocalConfig {}
 export interface IHomeAssistantWledConfig extends IWledConfig {}
 
-export const wledProfile: ISimpleLocalIntegrationProfile = {
-  domain: "wled",
-  displayName: "WLED",
-  manufacturer: "WLED",
-  model: "WLED controller",
-  defaultName: "WLED",
-  defaultPort: 80,
-  defaultHttpPath: "/json",
-  defaultProtocol: "http",
-  status: "control-runtime",
-  platforms: [
-    "light",
-    "sensor"
-  ],
-  serviceDomains: [
-    "light"
-  ],
-  controlServices: [
-    "turn_on",
-    "turn_off",
-    "toggle",
-    "set_level"
-  ],
-  discoverySources: [
-    "manual",
-    "mdns",
-    "ssdp",
-    "http",
-    "custom"
-  ],
-  discoveryKeywords: [
-    "wled",
-    "esp8266",
-    "esp32"
-  ],
+export interface IWledInfo {
+  mac: string;
+  name: string;
+  ver: string;
+  brand: 'WLED';
+  product?: string;
+  ws?: number;
+  leds: { count: number; maxseg: number; seglc?: number[] };
+}
+
+export interface IWledSegment {
+  id: number;
+  start: number;
+  stop: number;
+  on: boolean;
+  bri: number;
+  col: number[][];
+  n?: string;
+}
+
+export interface IWledState { on: boolean; bri: number; seg: IWledSegment[] }
+
+export interface IWledSnapshot {
+  info: IWledInfo;
+  state: IWledState;
+  updatedAt: string;
+}
+
+export type TWledRawData = { info: IWledInfo; state: IWledState };
+export interface IWledStateChange {
+  on?: boolean;
+  brightness?: number;
+  rgb?: [number, number, number];
+  white?: number;
+}
+export type TWledClientEvent =
+  | { type: 'snapshot'; snapshot: IWledSnapshot }
+  | { type: 'availability'; available: boolean }
+  | { type: 'error'; error: Error };
+
+export const wledProfile = {
+  domain: wledDomain,
+  displayName: wledDefaultName,
+  status: 'control-runtime',
   metadata: {
-    source: "home-assistant/core",
-    upstreamPath: "homeassistant/components/wled",
-    upstreamDomain: "wled",
-    integrationType: "device",
-    iotClass: "local_push",
-    qualityScale: "platinum",
-    requirements: [
-      "wled==0.22.0"
-    ],
-    dependencies: [],
-    afterDependencies: [],
-    codeowners: [
-      "@frenck",
-      "@mik-laj"
-    ],
+    source: 'native-typescript',
+    upstreamDomain: wledDomain,
+    integrationType: 'device',
+    iotClass: 'local_push',
     configFlow: true,
-    runtime: {
-      type: "control-runtime",
-      services: [
-        "snapshot",
-        "status",
-        "refresh",
-        "turn_on",
-        "turn_off",
-        "toggle",
-        "set_level"
-      ],
-      platforms: [
-        "light",
-        "sensor"
-      ],
-      controls: true
-    },
-    localApi: {
-      implemented: [
-        "manual local endpoint setup",
-        "snapshot, raw data, snapshotProvider, and injected native client operation",
-        "generic HTTP/TCP local transport when config.path, config.transport, or documented defaults are supplied"
-      ],
-      explicitUnsupported: [
-        "claiming live command success without injected client.execute or commandExecutor",
-        "cloud account flows and remote API polling",
-        "device-specific protocol features not represented by snapshot/rawData/client/executor inputs"
-      ]
-    }
-  }
-};
+    runtime: { type: 'control-runtime', platforms: ['light'], services: ['turn_on', 'turn_off', 'set_level', 'set_color'], controls: true },
+  },
+} as const;

package/ts/integrations/wled/wled.validation.ts

@@ -0,0 +1,72 @@
+import * as plugins from '../../plugins.js';
+import { DeviceCommunicationError } from '../../core/errors.js';
+import type { IWledConfig, IWledInfo, IWledSegment, IWledSnapshot, IWledState } from './wled.types.js';
+
+export const isWledRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+export const wledInteger = (valueArg: unknown, minArg: number, maxArg: number): valueArg is number =>
+  typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= minArg && valueArg <= maxArg;
+
+export const normalizeWledMac = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string' || !/^(?:[a-f\d]{12}|(?:[a-f\d]{2}:){5}[a-f\d]{2})$/i.test(valueArg)) throw new Error('WLED requires a valid 12-digit MAC identity.');
+  return valueArg.replace(/:/g, '').toLowerCase();
+};
+
+export const wledConfig = (valueArg: unknown): IWledConfig => {
+  if (!isWledRecord(valueArg) || Object.getPrototypeOf(valueArg) !== Object.prototype) throw new Error('WLED config must be a plain object.');
+  const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+  if (Reflect.ownKeys(valueArg).some((keyArg) => typeof keyArg !== 'string' || !['host', 'port', 'expectedMac', 'requestTimeoutMs'].includes(keyArg) || !('value' in descriptors[keyArg]))) throw new Error('WLED config contains unsupported settings or accessors.');
+  const host = valueArg.host;
+  if (typeof host !== 'string' || !host || /[\s\/?#@\\%]/.test(host)) throw new Error('WLED host must be an explicit hostname or IP address.');
+  const ip = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+  if (!plugins.net.isIP(ip) && !/^(?=.{1,253}$)(?:[a-z\d](?:[a-z\d-]{0,61}[a-z\d])?\.)*[a-z\d](?:[a-z\d-]{0,61}[a-z\d])?\.?$/i.test(host)) throw new Error('WLED host must be an explicit hostname or IP address.');
+  const port = valueArg.port === undefined ? 80 : valueArg.port;
+  const timeout = valueArg.requestTimeoutMs === undefined ? 5000 : valueArg.requestTimeoutMs;
+  if (!wledInteger(port, 1, 65535) || !wledInteger(timeout, 10, 60000)) throw new Error('WLED port or request timeout is invalid.');
+  return { host, port, requestTimeoutMs: timeout, expectedMac: valueArg.expectedMac === undefined ? undefined : normalizeWledMac(valueArg.expectedMac) };
+};
+
+export const wledEndpoint = (configArg: IWledConfig): URL => {
+  const host = configArg.host.includes(':') && !configArg.host.startsWith('[') ? `[${configArg.host}]` : configArg.host;
+  return new URL(`http://${host}:${configArg.port ?? 80}`);
+};
+
+const text = (valueArg: unknown, requiredArg = true): valueArg is string =>
+  typeof valueArg === 'string' && (!requiredArg || valueArg.length > 0) && valueArg.length <= 256 && !/[\u0000-\u001f\u007f]/.test(valueArg);
+
+export const parseWledSnapshot = (valueArg: unknown, expectedMacArg?: string): IWledSnapshot => {
+  const invalid = (): never => { throw new DeviceCommunicationError('WLED returned an invalid state and device information payload.'); };
+  if (!isWledRecord(valueArg) || !isWledRecord(valueArg.info) || !isWledRecord(valueArg.state)) return invalid();
+  const infoValue = valueArg.info;
+  const stateValue = valueArg.state;
+  if (!text(infoValue.name) || !text(infoValue.ver) || infoValue.brand !== 'WLED' || !isWledRecord(infoValue.leds)) return invalid();
+  let mac: string;
+  try { mac = normalizeWledMac(infoValue.mac); } catch { return invalid(); }
+  if (expectedMacArg !== undefined && expectedMacArg !== mac) throw new DeviceCommunicationError('WLED endpoint device identity changed or does not match the configured MAC.');
+  const ledsValue = infoValue.leds;
+  if (!wledInteger(ledsValue.count, 1, 65535) || !wledInteger(ledsValue.maxseg, 1, 255)) return invalid();
+  if (infoValue.product !== undefined && !text(infoValue.product) || infoValue.ws !== undefined && !wledInteger(infoValue.ws, -1, 255)) return invalid();
+  if (ledsValue.seglc !== undefined && (!Array.isArray(ledsValue.seglc) || ledsValue.seglc.length > ledsValue.maxseg || ledsValue.seglc.some((entryArg: unknown) => !wledInteger(entryArg, 0, 255)))) return invalid();
+  if (typeof stateValue.on !== 'boolean' || !wledInteger(stateValue.bri, 1, 255) || !Array.isArray(stateValue.seg) || stateValue.seg.length > ledsValue.maxseg) return invalid();
+  const segments: IWledSegment[] = [];
+  const ids = new Set<number>();
+  for (const [index, entry] of stateValue.seg.entries()) {
+    if (!isWledRecord(entry)) return invalid();
+    const id = entry.id ?? index;
+    if (!wledInteger(id, 0, ledsValue.maxseg - 1) || ids.has(id) || !wledInteger(entry.start, 0, ledsValue.count) || !wledInteger(entry.stop, 0, ledsValue.count)) return invalid();
+    ids.add(id);
+    if (entry.stop <= entry.start) continue;
+    if (typeof entry.on !== 'boolean' || !wledInteger(entry.bri, 0, 255) || !Array.isArray(entry.col) || entry.col.length < 1 || entry.col.length > 3 || entry.n !== undefined && !text(entry.n, false)) return invalid();
+    const colors: number[][] = [];
+    for (const color of entry.col) {
+      if (!Array.isArray(color) || ![3, 4].includes(color.length) || color.some((channelArg: unknown) => !wledInteger(channelArg, 0, 255))) return invalid();
+      colors.push([...color]);
+    }
+    segments.push({ id, start: entry.start, stop: entry.stop, on: entry.on, bri: entry.bri, col: colors, n: entry.n });
+  }
+  const info: IWledInfo = { mac, name: infoValue.name, ver: infoValue.ver, brand: 'WLED', product: infoValue.product, ws: infoValue.ws,
+    leds: { count: ledsValue.count, maxseg: ledsValue.maxseg, seglc: ledsValue.seglc === undefined ? undefined : [...ledsValue.seglc] } };
+  const state: IWledState = { on: stateValue.on, bri: stateValue.bri, seg: segments.sort((leftArg, rightArg) => leftArg.id - rightArg.id) };
+  return { info, state, updatedAt: new Date().toISOString() };
+};

package/ts/integrations/yeelight/readme.md

@@ -0,0 +1,47 @@
+# Native Yeelight LAN integration
+
+This integration uses `YeelightProtocol` and `probeYeelight` from published `@ecobridge.xyz/devicemanager` 4.3.0. The owning package implements vendor discovery and the bounded TCP protocol; this adapter admits one bulb into one home and maps its observed light properties.
+
+Enable **LAN Control** in the Yeelight app. Configure the bulb's private, link-local or loopback IPv4 address, the hub's local IPv4 interface and the expected hexadecimal device ID from vendor discovery. Hostnames, public endpoints, injected snapshots, command executors and arbitrary commands are rejected. Setup verifies a fresh sender-bound advertisement and matching ID before opening TCP, then requires a valid authoritative `get_prop` response. The config flow verifies this live admission and closes its temporary client before returning configuration; runtime setup independently admits the device again. Discovery and TCP identifiers are unauthenticated and unencrypted; a matching ID does not establish cryptographic device identity or owner authorization.
+
+```typescript
+const configStore = new NoSqlConfigStore({
+  db,
+  keyProvider,
+  homeId: 'my-home',
+  integrationDomain: 'yeelight',
+});
+await configStore.initialize();
+
+const integration = new YeelightIntegration();
+const runtime = await integration.setup({
+  homeId: 'my-home',
+  host: '192.168.1.20',
+  localAddress: '192.168.1.10',
+  expectedId: '0x000000000015243f',
+  requestTimeoutMs: 5000,
+}, { configStore, abortSignal });
+
+const [entity] = await runtime.entities();
+const result = await runtime.callService?.({
+  domain: 'light', service: 'turn_on', target: { entityId: entity.id },
+});
+await integration.destroy();
+await configStore.close();
+```
+
+The caller owns the encrypted config store, database and key provider. Setup and every queued operation require its `getScope()` to match both `homeId` and `yeelight`. The integration does not create a persistence fallback or close caller-owned resources. Device and light entity IDs include the home and vendor ID and remain stable across renames; these IDs replace the earlier name-derived entity IDs and home-independent device IDs.
+
+`devices()` and `entities()` obtain fresh authoritative properties. Push `props` notifications merge validated observed fields into the last observation; returned snapshots and event payloads are detached. A command result never manufactures physical state. RGB, colour temperature and HSV values are reported only when the bulb reports their corresponding active colour mode. Colour temperature is read-only even when the vendor advertises `set_ct_abx`, because this adapter exposes only the published protocol's supported controls.
+
+Supported services are `light.turn_on`, `light.turn_off`, `light.set_brightness` with `data.brightness`, and `light.set_rgb` with `data.rgbColor`. Power services accept no extra data. Each call sends at most one effect; compound power/brightness/colour changes are rejected. Targets require the exact current device or light entity ID; supplying both requires both to match. Feature writes accept boolean `power`, integer `brightness` 1–100 and canonical RGB text such as `255,0,128`. RGB services accept a dense three-integer array with channels 0–255. The current admitted method list owns writability; caller-supplied feature permissions grant nothing. Invalid values reject without rounding or clamping.
+
+The transition is configured once with `effect: 'smooth' | 'sudden'` and integer `transitionMs` (default 350 ms; smooth requires at least 30 ms). Scenes, colour flows, music mode, background-channel controls, colour temperature writes, arbitrary commands and automatic reconnection are unsupported. A matching command acknowledgement followed by successful observed-state read-back returns `success: true` with `effectOutcome: 'acknowledged'`; it does not assert that the requested physical state was achieved. Rejection retains `rejected`; loss of acknowledgement or failed read-back after acceptance is `indeterminate`. No effect is retried or replayed. An indeterminate result also blocks later queued effects until an explicit fresh `devices()`, `entities()` or client `getSnapshot()` read succeeds; notifications alone do not clear that admission hold.
+
+One client admits at most 16 pending integration operations and 32 subscriptions. The configured 1–60000 ms deadline covers a queued operation through control/read-back; queued cancellation refuses dispatch promptly, while cancellation after dispatch retains the protocol's effect classification. Setup has the same whole-startup deadline. The upstream connection bounds frames and commands and enforces its documented per-connection quota. External LAN clients remain outside that quota and state coordination.
+
+Subscriptions dispose independently and may use an `AbortSignal`. Callback failure or invalid authoritative properties terminates the TCP protocol and makes `isHealthy()` false. Runtime and integration destruction reject new admissions, cancel discovery/requests, remove callbacks, drain queued/startup work and await owned socket closure. Cleanup is terminal and idempotent. Setup's signal is released after successful startup; later operations and subscriptions use their own cancellation signals.
+
+Tests use actual loopback TCP and vendor multicast UDP fixtures. No real bulb or owner credentials have been used; physical acceptance against representative firmware remains outstanding.
+
+Protocol sources: [Yeelight WiFi Light Inter-Operation Specification](https://www.yeelight.com/download/Yeelight_Inter-Operation_Spec.pdf), [LAN Control setup](https://www.yeelight.com/faqs/lan_control), and the installed devicemanager 4.3.0 readme and declaration files.