@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/yamaha/yamaha.validation.ts

@@ -0,0 +1,86 @@
+import * as plugins from '../../plugins.js';
+import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import type { IYamahaConfig, TYamahaControl, TYamahaModel } from './yamaha.types.js';
+
+export function yamahaRecord(value: unknown, allowed?: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new TypeError('Yamaha input 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' || (allowed && !allowed.includes(key)) || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError('Yamaha input contains an unsupported field or accessor.');
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function yamahaText(value: unknown, label: string, maximum = 256): string {
+  if (typeof value !== 'string' || !value || value.length > maximum || value !== value.trim() || /[\p{Cc}\p{Cs}]/u.test(value)) {
+    throw new TypeError(`Yamaha ${label} must be bounded text without control characters.`);
+  }
+  return value;
+}
+
+export function yamahaOrigin(value: unknown): string {
+  const text = yamahaText(value, 'selected origin', 256);
+  const match = /^http:\/\/([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+)(?::([0-9]+))?\/?$/.exec(text);
+  if (!match || plugins.net.isIP(match[1]) !== 4) throw new TypeError('Yamaha requires a canonical literal private IPv4 HTTP origin.');
+  const octets = match[1].split('.').map(Number);
+  const [first, second] = octets;
+  if (!(first === 10 || first === 127 || (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 168) || (first === 169 && second === 254))) {
+    throw new TypeError('Yamaha requires a selected private, link-local or loopback IPv4 host.');
+  }
+  if (match[2] !== undefined && (!/^[1-9][0-9]{0,4}$/.test(match[2]) || Number(match[2]) > 65535)) {
+    throw new TypeError('Yamaha HTTP origin port is invalid.');
+  }
+  return new URL(text).origin;
+}
+
+export function yamahaDeviceId(value: unknown): string {
+  if (typeof value !== 'string' || !/^[\x21-\x7e]{12}$/.test(value)) throw new TypeError('Yamaha requires the exact 12-character device_id.');
+  return value;
+}
+
+export function yamahaModel(value: unknown): TYamahaModel {
+  if (value !== 'RX-V485') throw new TypeError('Yamaha model has no selected native profile.');
+  return value;
+}
+
+export function yamahaInteger(value: unknown, fallback?: number, minimum = Number.MIN_SAFE_INTEGER, maximum = Number.MAX_SAFE_INTEGER): number {
+  const result = value === undefined ? fallback : value;
+  if (typeof result !== 'number' || !Number.isSafeInteger(result) || result < minimum || result > maximum) throw new RangeError('Yamaha integer bound is invalid.');
+  return result;
+}
+
+export function normalizeYamahaConfig(value: unknown): Readonly<Required<Omit<IYamahaConfig, 'name'>> & Pick<IYamahaConfig, 'name'>> {
+  const config = yamahaRecord(value, ['homeId', 'origin', 'expectedDeviceId', 'model', 'allowUnencryptedHttp', 'maxVolume', 'name', 'timeoutMs', 'maxResponseBytes', 'maxPendingOperations']);
+  if (config.allowUnencryptedHttp !== true) throw new TypeError('Yamaha plaintext LAN trust must be acknowledged explicitly.');
+  return Object.freeze({
+    homeId: yamahaText(config.homeId, 'home ID'), origin: yamahaOrigin(config.origin), expectedDeviceId: yamahaDeviceId(config.expectedDeviceId),
+    model: yamahaModel(config.model), allowUnencryptedHttp: true, maxVolume: yamahaInteger(config.maxVolume),
+    ...(config.name === undefined ? {} : { name: yamahaText(config.name, 'display name', 128) }),
+    timeoutMs: yamahaInteger(config.timeoutMs, 5000, 1, 60000), maxResponseBytes: yamahaInteger(config.maxResponseBytes, 65536, 256, 1048576),
+    maxPendingOperations: yamahaInteger(config.maxPendingOperations, 16, 1, 128),
+  });
+}
+
+/** The authorized host owns the optional store and its immutable home/domain declaration. */
+export function assertYamahaScope(store: NoSqlConfigStore | undefined, homeId: string): void {
+  if (store === undefined) return;
+  if (!(store instanceof NoSqlConfigStore)) throw new TypeError('Yamaha config store must be an actual NoSqlConfigStore.');
+  const scope = NoSqlConfigStore.prototype.getScope.call(store);
+  if (scope.homeId !== homeId || scope.integrationDomain !== 'yamaha') throw new Error('Yamaha config store must match the exact home and integration.');
+}
+
+export function validateYamahaControl(value: unknown): TYamahaControl {
+  const control = yamahaRecord(value, ['feature', 'value']);
+  if (control.feature === 'power' && typeof control.value === 'boolean') return { feature: 'power', value: control.value };
+  if (control.feature === 'muted' && typeof control.value === 'boolean') return { feature: 'muted', value: control.value };
+  if (control.feature === 'volume_raw') return { feature: 'volume_raw', value: yamahaInteger(control.value) };
+  if (control.feature === 'input' && typeof control.value === 'string' && /^[a-z][a-z0-9_]{0,63}$/.test(control.value)) return { feature: 'input', value: control.value };
+  throw new TypeError('Yamaha supports explicit power, mute, raw integer volume and current advertised input controls.');
+}

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.