@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/denonavr/denonavr.types.ts

@@ -1,117 +1,57 @@
-export type TDenonavrZone = 'Main' | 'Zone2' | 'Zone3';
-
-export type TDenonavrPowerState = 'ON' | 'STANDBY' | 'OFF' | string;
-
-export type TDenonavrMediaState = 'on' | 'off' | 'playing' | 'paused' | 'stopped' | 'idle' | string;
-
-export type TDenonavrReceiverType = 'avr' | 'avr-x' | 'avr-x-2016' | string;
-
-export type TDenonavrCommand =
-  | 'turn_on'
-  | 'turn_off'
-  | 'volume_up'
-  | 'volume_down'
-  | 'set_volume'
-  | 'mute'
-  | 'select_source'
-  | 'play'
-  | 'pause'
-  | 'stop'
-  | 'play_pause'
-  | 'previous_track'
-  | 'next_track'
-  | 'get_command';
+export type TDenonavrModel = 'AVR-1913' | 'AVR-2113CI' | 'NR1605' | 'SR5009';
 
 export interface IDenonavrConfig {
-  host?: string;
-  port?: number;
+  homeId: string;
+  host: string;
+  descriptionUrl: string;
+  expectedUdn: string;
+  model: TDenonavrModel;
+  maximumVolumeDb: number;
   name?: string;
-  model?: string;
-  manufacturer?: string;
-  serialNumber?: string;
-  receiverType?: TDenonavrReceiverType;
-  descriptionPort?: number;
-  showAllSources?: boolean;
-  zone2?: boolean;
-  zone3?: boolean;
-  sourceMap?: Record<string, string>;
-  receiverInfo?: IDenonavrReceiverInfo;
-  zones?: IDenonavrZoneState[];
-  snapshot?: IDenonavrSnapshot;
-}
-
-export interface IHomeAssistantDenonavrConfig extends IDenonavrConfig {}
-
-export interface IDenonavrReceiverInfo {
-  host?: string;
   port?: number;
-  name?: string;
-  friendlyName?: string;
-  manufacturer?: string;
-  modelName?: string;
-  modelNumber?: string;
-  serialNumber?: string;
-  receiverType?: TDenonavrReceiverType;
-  receiverPort?: number;
-  presentationUrl?: string;
-  softwareVersion?: string;
+  timeoutMs?: number;
+  maxPendingOperations?: number;
+  maxDescriptionBytes?: number;
 }
 
-export interface IDenonavrMediaInfo {
-  title?: string;
-  artist?: string;
-  album?: string;
-  band?: string;
-  frequency?: string;
-  station?: string;
-  imageUrl?: string;
-  contentType?: string;
-}
+export interface IHomeAssistantDenonavrConfig extends IDenonavrConfig {}
 
-export interface IDenonavrZoneState {
-  zone: TDenonavrZone;
-  name?: string;
-  power?: TDenonavrPowerState;
-  state?: TDenonavrMediaState;
-  volumeDb?: number;
-  volumeLevel?: number;
-  muted?: boolean;
-  source?: string;
-  sourceList?: string[];
-  sourceMap?: Record<string, string>;
-  soundMode?: string;
-  soundModeRaw?: string;
-  soundModeList?: string[];
-  dynamicEq?: boolean;
-  ecoMode?: string;
-  media?: IDenonavrMediaInfo;
-  available?: boolean;
+export interface IDenonavrIdentity {
+  readonly udn: string;
+  readonly manufacturer: 'Denon' | 'Marantz';
+  readonly model: TDenonavrModel;
+  readonly name: string;
+  readonly serialNumber?: string;
+  readonly source: 'selected-upnp-description';
+  readonly observedAt: string;
 }
 
+/** Receiver settings are observations, not proof of electrical or acoustic effects. */
 export interface IDenonavrSnapshot {
-  receiverInfo: IDenonavrReceiverInfo;
-  zones: IDenonavrZoneState[];
-  events?: IDenonavrEvent[];
-  lastUpdated?: string;
+  readonly homeId: string;
+  readonly host: string;
+  readonly port: number;
+  readonly name: string;
+  readonly identity: IDenonavrIdentity;
+  readonly power: 'on' | 'standby';
+  readonly muted: boolean;
+  readonly volumeDb: number | null;
+  readonly input: string;
+  readonly observedInputs: readonly string[];
+  readonly maximumVolumeDb: number;
+  readonly observedAt: string;
 }
 
-export interface IDenonavrCommandRequest {
-  command: TDenonavrCommand;
-  zone?: TDenonavrZone;
-  source?: string;
-  volumeLevel?: number;
-  volumeDb?: number;
-  muted?: boolean;
-  path?: string;
-}
+export type TDenonavrControl =
+  | { feature: 'power'; value: boolean }
+  | { feature: 'muted'; value: boolean }
+  | { feature: 'volume_db'; value: number }
+  | { feature: 'input'; value: string };
 
-export interface IDenonavrEvent {
-  type: 'telnet' | 'http' | 'state';
-  zone?: TDenonavrZone;
-  event?: string;
-  parameter?: string;
-  command?: TDenonavrCommand;
-  timestamp: number;
+export interface IDenonavrEffectResult {
+  readonly dispatch: 'written';
+  readonly outcome: 'observed-target' | 'indeterminate';
+  readonly snapshot: IDenonavrSnapshot;
 }
 
 export interface IDenonavrSsdpRecord {
@@ -122,21 +62,18 @@ export interface IDenonavrSsdpRecord {
   upnp?: Record<string, string | undefined>;
 }
 
-export interface IDenonavrMdnsRecord {
-  name?: string;
-  type?: string;
-  host?: string;
-  port?: number;
-  txt?: Record<string, string | undefined>;
-}
-
 export interface IDenonavrManualEntry {
   host?: string;
-  port?: number;
+  descriptionUrl?: string;
+  expectedUdn?: string;
   id?: string;
   name?: string;
   manufacturer?: string;
   model?: string;
-  serialNumber?: string;
   metadata?: Record<string, unknown>;
 }
+
+export interface IDenonavrIntegrationOptions {
+  readonly homeId?: string;
+  readonly capacity?: number;
+}

package/ts/integrations/denonavr/denonavr.validation.ts

@@ -0,0 +1,87 @@
+import * as plugins from '../../plugins.js';
+import type { IDenonavrConfig, TDenonavrControl, TDenonavrModel } from './denonavr.types.js';
+
+export function denonavrRecord(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('DenonAVR 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('DenonAVR input contains an unsupported field or accessor.');
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function denonavrText(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(`DenonAVR ${label} must be bounded text without control characters.`);
+  }
+  return value;
+}
+
+export function denonavrHost(value: unknown): string {
+  if (typeof value !== 'string' || plugins.net.isIP(value) !== 4) throw new TypeError('DenonAVR requires a selected private IPv4 address.');
+  const [first, second, , last] = value.split('.').map(Number);
+  if (!(first === 10 || first === 127 || (first === 172 && second >= 16 && second <= 31) || (first === 192 && second === 168)) || last === 0 || last === 255) {
+    throw new TypeError('DenonAVR requires a selected private or loopback host IPv4 address.');
+  }
+  return value;
+}
+
+export function denonavrModel(value: unknown): TDenonavrModel {
+  if (value !== 'AVR-1913' && value !== 'AVR-2113CI' && value !== 'NR1605' && value !== 'SR5009') throw new TypeError('DenonAVR model has no documented selected-receiver profile.');
+  return value;
+}
+
+export function denonavrUdn(value: unknown): string {
+  if (typeof value !== 'string' || !/^uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)) throw new TypeError('DenonAVR requires an exact UPnP UUID.');
+  return value.toLowerCase();
+}
+
+export function denonavrDescription(value: unknown, host: string): string {
+  const text = denonavrText(value, 'description URL', 2048);
+  const url = new URL(text);
+  if (url.protocol !== 'http:' || url.hostname !== host || url.username || url.password || url.search || url.hash || url.pathname === '/') {
+    throw new TypeError('DenonAVR description URL must select an HTTP path at the receiver IP without credentials, query or fragment.');
+  }
+  return url.href;
+}
+
+export function denonavrVolume(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < -79.5 || value > 18 || !Number.isInteger(value * 2)) {
+    throw new TypeError('DenonAVR absolute volume must be -79.5 through 18 dB in half-decibel steps.');
+  }
+  return value;
+}
+
+function integer(value: unknown, fallback: number, minimum: number, maximum: number): number {
+  if (value === undefined) return fallback;
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new RangeError('DenonAVR numeric bound is invalid.');
+  return value;
+}
+
+export function normalizeDenonavrConfig(value: unknown): Readonly<Required<Omit<IDenonavrConfig, 'name'>> & Pick<IDenonavrConfig, 'name'>> {
+  const config = denonavrRecord(value, ['homeId', 'host', 'descriptionUrl', 'expectedUdn', 'model', 'maximumVolumeDb', 'name', 'port', 'timeoutMs', 'maxPendingOperations', 'maxDescriptionBytes']);
+  const host = denonavrHost(config.host);
+  return Object.freeze({
+    homeId: denonavrText(config.homeId, 'home ID'), host,
+    descriptionUrl: denonavrDescription(config.descriptionUrl, host), expectedUdn: denonavrUdn(config.expectedUdn),
+    model: denonavrModel(config.model), maximumVolumeDb: denonavrVolume(config.maximumVolumeDb),
+    ...(config.name === undefined ? {} : { name: denonavrText(config.name, 'name', 128) }),
+    port: integer(config.port, 23, 1, 65535), timeoutMs: integer(config.timeoutMs, 5000, 1, 60000),
+    maxPendingOperations: integer(config.maxPendingOperations, 16, 1, 128), maxDescriptionBytes: integer(config.maxDescriptionBytes, 65536, 256, 1048576),
+  });
+}
+
+export function validateDenonavrControl(value: unknown): TDenonavrControl {
+  const control = denonavrRecord(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_db') return { feature: 'volume_db', value: denonavrVolume(control.value) };
+  if (control.feature === 'input') return { feature: 'input', value: denonavrText(control.value, 'physical input', 25) };
+  throw new TypeError('DenonAVR supports one explicit power, mute, absolute volume or observed physical input control.');
+}