@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/deconz/deconz.validation.ts

@@ -0,0 +1,261 @@
+import type { IDeconzConfig, IDeconzGatewayConfig, IDeconzGroupActionPatch, IDeconzLightingStatePatch, IDeconzLightStatePatch, IDeconzSensorConfigPatch, IDeconzSnapshot, IDeconzWebsocketEvent } from './deconz.types.js';
+
+type TDeconzPatchValue = string | number | boolean | number[];
+type TDeconzPatchValidator = (valueArg: unknown) => boolean;
+
+function integerRange(minArg: number, maxArg: number): TDeconzPatchValidator {
+  return (valueArg) => typeof valueArg === 'number' && Number.isInteger(valueArg) && valueArg >= minArg && valueArg <= maxArg;
+}
+
+function stringValues(valuesArg: readonly string[]): TDeconzPatchValidator {
+  return (valueArg) => typeof valueArg === 'string' && valuesArg.includes(valueArg);
+}
+
+const booleanValue: TDeconzPatchValidator = (valueArg) => typeof valueArg === 'boolean';
+const effectValue: TDeconzPatchValidator = (valueArg) => typeof valueArg === 'string' && valueArg.length > 0;
+const xyValue: TDeconzPatchValidator = (valueArg) => {
+  if (!Array.isArray(valueArg) || valueArg.length !== 2 || Reflect.ownKeys(valueArg).some((keyArg) => keyArg !== '0' && keyArg !== '1' && keyArg !== 'length')) return false;
+  return ['0', '1'].every((keyArg) => {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, keyArg);
+    const value: unknown = descriptor?.value;
+    return descriptor?.enumerable && 'value' in descriptor && typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+  });
+};
+
+const LIGHTING_PATCH_FIELDS = {
+  alert: stringValues(['none', 'select', 'lselect', 'blink', 'breathe', 'okay', 'channelchange', 'finish', 'stop']),
+  bri: integerRange(0, 255),
+  colorloopspeed: integerRange(1, 255),
+  ct: integerRange(1, 65535),
+  effect: effectValue,
+  hue: integerRange(0, 65535),
+  on: booleanValue,
+  sat: integerRange(0, 255),
+  transitiontime: integerRange(0, 65535),
+  xy: xyValue,
+} satisfies Record<keyof IDeconzLightingStatePatch, TDeconzPatchValidator>;
+
+const LIGHT_PATCH_FIELDS = {
+  ...LIGHTING_PATCH_FIELDS,
+  lift: (valueArg: unknown) => valueArg === 'stop' || integerRange(0, 100)(valueArg),
+  open: booleanValue,
+  speed: integerRange(0, 6),
+  stop: booleanValue,
+  tilt: integerRange(0, 100),
+} satisfies Record<keyof IDeconzLightStatePatch, TDeconzPatchValidator>;
+
+const GROUP_PATCH_FIELDS = {
+  ...LIGHTING_PATCH_FIELDS,
+  alert: stringValues(['none', 'select', 'lselect']),
+  effect: stringValues(['none', 'colorloop']),
+  toggle: booleanValue,
+} satisfies Record<keyof IDeconzGroupActionPatch, TDeconzPatchValidator>;
+
+const SENSOR_CONFIG_PATCH_FIELDS = {
+  battery: integerRange(0, 100),
+  coolsetpoint: integerRange(700, 3500),
+  fanmode: stringValues(['off', 'low', 'medium', 'high', 'on', 'auto', 'smart']),
+  heatsetpoint: integerRange(500, 3200),
+  locked: booleanValue,
+  mode: stringValues(['momentary', 'rocker', 'off', 'auto', 'cool', 'heat', 'emergency heating', 'precooling', 'fan only', 'dry', 'sleep']),
+  offset: integerRange(-32768, 32767),
+  on: booleanValue,
+  preset: stringValues(['holiday', 'auto', 'manual', 'comfort', 'eco', 'boost', 'complex']),
+  reachable: booleanValue,
+  setvalve: booleanValue,
+} satisfies Record<keyof IDeconzSensorConfigPatch, TDeconzPatchValidator>;
+
+function writePatch(valueArg: unknown, fieldsArg: Readonly<Record<string, TDeconzPatchValidator>>): Record<string, TDeconzPatchValue> {
+  record(valueArg);
+  const prototype: unknown = Object.getPrototypeOf(valueArg);
+  if (prototype !== Object.prototype && prototype !== null) throw new Error('Invalid deCONZ write patch object.');
+  const keys = Reflect.ownKeys(valueArg);
+  if (!keys.length) throw new Error('deCONZ write patch must not be empty.');
+  const result = Object.create(null) as Record<string, TDeconzPatchValue>;
+  for (const key of keys) {
+    if (typeof key !== 'string' || !Object.hasOwn(fieldsArg, key)) throw new Error('Unsupported deCONZ write patch field.');
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    const value: unknown = descriptor?.value;
+    if (!descriptor?.enumerable || !('value' in descriptor) || !fieldsArg[key](value)) throw new Error('Invalid deCONZ write patch field.');
+    result[key] = Array.isArray(value) ? [value[0] as number, value[1] as number] : value as string | number | boolean;
+  }
+  if (result.colorloopspeed !== undefined && result.effect !== 'colorloop') throw new Error('deCONZ colorloopspeed requires effect colorloop.');
+  return result;
+}
+
+export function deconzLightStatePatch(valueArg: unknown): Record<string, TDeconzPatchValue> {
+  return writePatch(valueArg, LIGHT_PATCH_FIELDS);
+}
+
+export function deconzGroupActionPatch(valueArg: unknown): Record<string, TDeconzPatchValue> {
+  return writePatch(valueArg, GROUP_PATCH_FIELDS);
+}
+
+export function deconzSensorConfigPatch(valueArg: unknown): Record<string, TDeconzPatchValue> {
+  return writePatch(valueArg, SENSOR_CONFIG_PATCH_FIELDS);
+}
+
+const CLIP_STATE_KEYS: Record<string, readonly string[]> = {
+  CLIPAlarm: ['alarm'], CLIPBattery: ['battery'], CLIPCarbonMonoxide: ['carbonmonoxide'],
+  CLIPConsumption: ['consumption'], CLIPFire: ['fire'], CLIPGenericFlag: ['flag'],
+  CLIPGenericStatus: ['status'], CLIPHumidity: ['humidity'], CLIPLightLevel: ['lightlevel', 'lux', 'dark', 'daylight'],
+  CLIPOpenClose: ['open'], CLIPPower: ['power', 'voltage', 'current'], CLIPPresence: ['presence', 'duration'],
+  CLIPPressure: ['pressure'], CLIPSwitch: ['buttonevent'], CLIPTemperature: ['temperature'],
+  CLIPVibration: ['vibration'], CLIPWater: ['water'],
+};
+
+export function deconzWritableState(typeArg: string | undefined, keyArg: string): boolean {
+  return Boolean(typeArg && CLIP_STATE_KEYS[typeArg]?.includes(keyArg));
+}
+
+export function deconzSensorStatePatch(typeArg: string | undefined, valueArg: unknown): void {
+  record(valueArg);
+  state(valueArg);
+  if (!Object.keys(valueArg).length || Object.keys(valueArg).some((keyArg) => !deconzWritableState(typeArg, keyArg))) throw new Error('Unsupported deCONZ CLIP sensor state field.');
+  for (const [key, value] of Object.entries(valueArg)) {
+    const booleanKey = ['alarm', 'carbonmonoxide', 'fire', 'flag', 'open', 'presence', 'vibration', 'water', 'dark', 'daylight'].includes(key);
+    if (booleanKey && typeof value !== 'boolean' || !booleanKey && typeof value !== 'number') throw new Error('Invalid deCONZ CLIP state value type.');
+    if (typeof value !== 'boolean' && (typeof value !== 'number' || !Number.isSafeInteger(value))) throw new Error('Invalid deCONZ CLIP state value.');
+    const range = key === 'temperature' || key === 'power' || key === 'pressure' ? [-32768, 32767] : key === 'status' ? [-2147483648, 2147483647] : key === 'consumption' ? [0, Number.MAX_SAFE_INTEGER] : key === 'lux' || key === 'buttonevent' ? [0, 4294967295] : key === 'battery' ? [0, 100] : [0, 65535];
+    if (typeof value === 'number' && (value < range[0] || value > range[1])) throw new Error('deCONZ CLIP state value is out of range.');
+  }
+}
+
+export function isDeconzRecord(valueArg: unknown): valueArg is Record<string, unknown> {
+  return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+}
+
+function record(valueArg: unknown): asserts valueArg is Record<string, unknown> {
+  if (!isDeconzRecord(valueArg)) throw new Error('Invalid deCONZ response shape.');
+}
+
+function fields(valueArg: Record<string, unknown>, keysArg: string[], typeArg: 'string' | 'number' | 'boolean'): void {
+  for (const key of keysArg) {
+    const value = valueArg[key];
+    if (value !== undefined && (typeof value !== typeArg || typeArg === 'number' && !Number.isFinite(value))) {
+      throw new Error('Invalid deCONZ response field.');
+    }
+  }
+}
+
+export function deconzPort(valueArg: unknown): number {
+  if (typeof valueArg !== 'number' || !Number.isInteger(valueArg) || valueArg < 1 || valueArg > 65535) {
+    throw new Error('deCONZ port must be an integer from 1 to 65535.');
+  }
+  return valueArg;
+}
+
+export function deconzEndpoint(configArg: IDeconzConfig): URL {
+  if (configArg.protocol !== undefined && configArg.protocol !== 'http' && configArg.protocol !== 'https') {
+    throw new Error('deCONZ protocol must be http or https.');
+  }
+  const host = configArg.host;
+  if (typeof host !== 'string' || !host || host.trim() !== host || /[\s/@?#]/.test(host)) {
+    throw new Error('deCONZ requires a host without credentials, paths or query parameters.');
+  }
+  const protocol = configArg.protocol ?? 'http';
+  const port = deconzPort(configArg.port ?? (protocol === 'https' ? 443 : 80));
+  const hostname = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+  let endpoint: URL;
+  try { endpoint = new URL(`${protocol}://${hostname}:${port}`); }
+  catch { throw new Error('Invalid deCONZ host.'); }
+  if (endpoint.pathname !== '/' || endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    throw new Error('Invalid deCONZ endpoint.');
+  }
+  return endpoint;
+}
+
+export function deconzGatewayConfig(valueArg: unknown): IDeconzGatewayConfig {
+  record(valueArg);
+  const stringKeys = ['apiversion', 'bridgeid', 'devicename', 'fwversion', 'ipaddress', 'mac', 'modelid', 'name', 'swversion', 'uuid'];
+  fields(valueArg, stringKeys, 'string');
+  fields(valueArg, ['rfconnected', 'websocketnotifyall'], 'boolean');
+  if (valueArg.websocketport !== undefined) deconzPort(valueArg.websocketport);
+  if (valueArg.bridgeid !== undefined && (typeof valueArg.bridgeid !== 'string' || !/^[a-f0-9]{16}$/i.test(valueArg.bridgeid)) || valueArg.uuid !== undefined && (typeof valueArg.uuid !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(valueArg.uuid))) throw new Error('Invalid deCONZ gateway identity.');
+  if (!valueArg.bridgeid && !valueArg.uuid || valueArg.modelid !== undefined && valueArg.modelid !== 'deCONZ') {
+    throw new Error('Response is not an identified deCONZ gateway.');
+  }
+  const result: IDeconzGatewayConfig = {};
+  for (const key of [...stringKeys, 'rfconnected', 'websocketnotifyall', 'websocketport']) {
+    if (valueArg[key] !== undefined) result[key] = valueArg[key];
+  }
+  return result;
+}
+
+function state(valueArg: unknown): void {
+  record(valueArg);
+  if (Object.values(valueArg).some((entryArg) => typeof entryArg === 'number' && !Number.isFinite(entryArg))) throw new Error('Invalid deCONZ numeric state.');
+  fields(valueArg, ['alert', 'colormode', 'effect', 'airquality', 'lastupdated', 'mode', 'fanmode', 'preset'], 'string');
+  fields(valueArg, ['on', 'open', 'reachable', 'all_on', 'any_on', 'alarm', 'carbonmonoxide', 'fire', 'flag', 'presence', 'vibration', 'water', 'tampered', 'lowbattery', 'dark', 'daylight', 'locked', 'stop'], 'boolean');
+  fields(valueArg, ['bri', 'ct', 'hue', 'sat', 'tilt', 'speed', 'consumption', 'current', 'humidity', 'lux', 'lightlevel', 'power', 'pressure', 'status', 'temperature', 'voltage', 'heatsetpoint', 'coolsetpoint', 'offset', 'valve', 'airqualityppb'], 'number');
+  for (const key of ['battery', 'buttonevent']) {
+    if (valueArg[key] !== null) fields(valueArg, [key], 'number');
+  }
+  if (valueArg.lift !== undefined && valueArg.lift !== 'stop') fields(valueArg, ['lift'], 'number');
+  if (valueArg.xy !== undefined && (!Array.isArray(valueArg.xy) || valueArg.xy.length !== 2 || !valueArg.xy.every((itemArg) => typeof itemArg === 'number' && Number.isFinite(itemArg) && itemArg >= 0 && itemArg <= 1))) {
+    throw new Error('Invalid deCONZ color coordinates.');
+  }
+}
+
+function resource(valueArg: unknown, kindArg: 'lights' | 'groups' | 'sensors'): void {
+  record(valueArg);
+  fields(valueArg, ['id', 'name', 'type', 'uniqueid', 'manufacturername', 'modelid', 'swversion', 'etag'], 'string');
+  if (typeof valueArg.name !== 'string' || !valueArg.name || kindArg !== 'groups' && (typeof valueArg.type !== 'string' || !valueArg.type)) throw new Error('Invalid deCONZ resource description.');
+  record(valueArg.state);
+  if (kindArg === 'sensors') record(valueArg.config);
+  for (const key of ['state', 'config', 'action']) if (valueArg[key] !== undefined) state(valueArg[key]);
+  if (kindArg === 'groups') {
+    for (const key of ['lights', 'devicemembership', 'lightsequence', 'multideviceids']) {
+      const value = valueArg[key];
+      if (value !== undefined && (!Array.isArray(value) || !value.every((itemArg) => typeof itemArg === 'string'))) {
+        throw new Error('Invalid deCONZ group membership.');
+      }
+    }
+    if (valueArg.scenes !== undefined) {
+      const scenes = valueArg.scenes;
+      if (!Array.isArray(scenes) && !isDeconzRecord(scenes)) throw new Error('Invalid deCONZ scene references.');
+      for (const scene of Object.values(scenes)) {
+        record(scene);
+        fields(scene, ['id', 'name'], 'string');
+        if (typeof scene.id !== 'string' || !scene.id) throw new Error('Invalid deCONZ scene identity.');
+      }
+    }
+  }
+}
+
+export function deconzSnapshot(valueArg: unknown): IDeconzSnapshot {
+  record(valueArg);
+  const config = deconzGatewayConfig(valueArg.config);
+  for (const kind of ['lights', 'groups', 'sensors'] as const) {
+    record(valueArg[kind]);
+    for (const [id, item] of Object.entries(valueArg[kind])) {
+      if (!id) throw new Error('Invalid deCONZ resource identity.');
+      resource(item, kind);
+    }
+  }
+  if (valueArg.scenes !== undefined) {
+    record(valueArg.scenes);
+    for (const item of Object.values(valueArg.scenes)) {
+      record(item);
+      fields(item, ['id', 'groupId', 'name'], 'string');
+    }
+  }
+  return { ...valueArg, config } as IDeconzSnapshot;
+}
+
+export function deconzWebsocketEvent(valueArg: unknown): IDeconzWebsocketEvent {
+  record(valueArg);
+  if (valueArg.t !== 'event' || typeof valueArg.e !== 'string' || !['added', 'changed', 'deleted', 'scene-called'].includes(valueArg.e) || typeof valueArg.r !== 'string' || !['groups', 'lights', 'sensors', 'scenes'].includes(valueArg.r)) {
+    throw new Error('Invalid deCONZ event envelope.');
+  }
+  fields(valueArg, ['id', 'gid', 'scid', 'uniqueid', 'name'], 'string');
+  if (valueArg.e === 'scene-called') {
+    if (valueArg.r !== 'scenes' || !valueArg.gid || !valueArg.scid) throw new Error('Invalid deCONZ scene event.');
+  } else if (!valueArg.id) throw new Error('Invalid deCONZ event identity.');
+  for (const key of ['state', 'config']) if (valueArg[key] !== undefined) state(valueArg[key]);
+  for (const [key, kind] of [['light', 'lights'], ['group', 'groups'], ['sensor', 'sensors']] as const) {
+    if (valueArg[key] !== undefined) resource(valueArg[key], kind);
+    if (valueArg.e === 'added' && valueArg.r === kind && valueArg[key] === undefined) throw new Error('Invalid deCONZ added event.');
+  }
+  return valueArg as unknown as IDeconzWebsocketEvent;
+}

package/ts/integrations/deconz/readme.md

@@ -0,0 +1,44 @@
+# deCONZ integration
+
+Native deCONZ gateway pairing, authenticated REST snapshots and device controls, and WebSocket state events for smarthome.exchange.
+
+## 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.
+
+## Direct write contracts
+
+`DeconzClient.setLightState`, `setGroupState` and `setSensorConfig` accept explicit patch interfaces. Patches must be non-empty plain objects containing enumerable data properties. Unknown fields, nested objects, accessors, serialization hooks and values outside the protocol types or ranges are rejected before HTTP I/O. Read response fields such as light `reachable` and `colormode`, group `all_on`, and sensor `temperature`, `lowbattery`, `tampered` and `valve` are not write fields.
+
+| Method | Accepted fields |
+| --- | --- |
+| `setLightState` | `alert`, `bri`, `colorloopspeed`, `ct`, `effect`, `hue`, `on`, `sat`, `transitiontime`, `xy`, `lift`, `open`, `speed`, `stop`, `tilt` |
+| `setGroupState` | `alert`, `bri`, `colorloopspeed`, `ct`, `effect`, `hue`, `on`, `sat`, `transitiontime`, `xy`, `toggle` |
+| `setSensorConfig` | `battery`, `coolsetpoint`, `fanmode`, `heatsetpoint`, `locked`, `mode`, `offset`, `on`, `preset`, `reachable`, `setvalve` |
+
+Brightness and saturation use integers from 0 to 255; hue uses 0 to 65535; color coordinates are two finite numbers from 0 to 1. Color temperature is an integer from 1 to 65535 mireds; each device can impose narrower limits. Transition time uses integer tenths of a second from 0 to 65535. `colorloopspeed` uses 1 to 255 and requires `effect: 'colorloop'`. Light effect names remain device dependent and must be non-empty strings; group effects are `'none'` or `'colorloop'`. Light alert names include the gateway's documented identify and trigger effects; group alerts are `'none'`, `'select'` or `'lselect'`.
+
+Window covering `lift` is an integer percentage closed from 0 to 100 or `'stop'`; `tilt` uses 0 to 100 and fan `speed` uses 0 to 6. Sensor setpoints use hundredths of a degree: `heatsetpoint` is 500 to 3200 and `coolsetpoint` is 700 to 3500. `offset` uses a signed 16-bit integer. Sensor mode, fan mode and preset strings are restricted to the documented choices in `IDeconzSensorConfigPatch`. Availability of each write field still depends on the gateway resource; a protocol-valid patch does not grant a device capability.
+
+These contracts intentionally exclude arbitrary vendor fields and unvalidated nested structures such as thermostat schedules. The previous response-derived index signatures permitted such input without validation; callers must now use a supported typed field. Protocol references: [lights](https://dresden-elektronik.github.io/deconz-rest-doc/endpoints/lights/), [groups](https://dresden-elektronik.github.io/deconz-rest-doc/endpoints/groups/), [sensors](https://dresden-elektronik.github.io/deconz-rest-doc/endpoints/sensors/), and the gateway's [resource descriptors](https://github.com/dresden-elektronik/deconz-rest-plugin/blob/master/resource.cpp).
+
+## 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.