@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/pioneer/pioneer.validation.ts

@@ -0,0 +1,84 @@
+import * as plugins from '../../plugins.js';
+import type { IPioneerConfig, TPioneerControl } from './pioneer.types.js';
+
+export function pioneerRecord(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('Pioneer 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('Pioneer input contains an unsupported field or accessor.');
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function pioneerText(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(`Pioneer ${label} must be bounded text without control characters.`);
+  }
+  return value;
+}
+
+export function pioneerHost(value: unknown): string {
+  if (typeof value !== 'string' || plugins.net.isIP(value) !== 4) throw new TypeError('Pioneer 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('Pioneer requires a selected private or loopback IPv4 host.');
+  }
+  return value;
+}
+
+export function pioneerUdn(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('Pioneer requires an exact UPnP UUID.');
+  return value.toLowerCase();
+}
+
+export function pioneerDescription(value: unknown, host: string): string {
+  const url = new URL(pioneerText(value, 'description URL', 2048));
+  if (url.protocol !== 'http:' || url.hostname !== host || url.username || url.password || url.hash || url.search || url.pathname === '/') {
+    throw new TypeError('Pioneer description must select an HTTP path at the receiver IP without credentials, query or fragment.');
+  }
+  return url.href;
+}
+
+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('Pioneer numeric bound is invalid.');
+  return value;
+}
+
+export function pioneerVolume(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0 || value > 185) throw new TypeError('Pioneer volume must be a raw integer from 0 through 185.');
+  return value;
+}
+
+export const pioneerConfigKeys = ['homeId', 'host', 'descriptionUrl', 'expectedUdn', 'model', 'allowUnencryptedLan', 'maximumVolumeRaw', 'name', 'port', 'timeoutMs', 'maxPendingOperations', 'maxDescriptionBytes', 'maxFrameBytes'] as const;
+
+export function normalizePioneerConfig(value: unknown): Readonly<Required<Omit<IPioneerConfig, 'name'>> & Pick<IPioneerConfig, 'name'>> {
+  const config = pioneerRecord(value, pioneerConfigKeys);
+  const host = pioneerHost(config.host);
+  if (config.model !== 'SC-95') throw new TypeError('Pioneer model has no admitted vendor profile.');
+  if (config.allowUnencryptedLan !== true) throw new TypeError('Pioneer requires an explicit plaintext LAN acknowledgement.');
+  return Object.freeze({
+    homeId: pioneerText(config.homeId, 'home ID'), host, descriptionUrl: pioneerDescription(config.descriptionUrl, host),
+    expectedUdn: pioneerUdn(config.expectedUdn), model: config.model, allowUnencryptedLan: config.allowUnencryptedLan,
+    maximumVolumeRaw: pioneerVolume(config.maximumVolumeRaw),
+    ...(config.name === undefined ? {} : { name: pioneerText(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), maxFrameBytes: integer(config.maxFrameBytes, 512, 16, 4096),
+  });
+}
+
+export function validatePioneerControl(value: unknown): TPioneerControl {
+  const control = pioneerRecord(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: pioneerVolume(control.value) };
+  if (control.feature === 'input' && typeof control.value === 'string' && /^\d{2}$/.test(control.value)) return { feature: 'input', value: control.value };
+  throw new TypeError('Pioneer supports one explicit power, mute, raw volume or observed physical input control.');
+}