@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/soundtouch/soundtouch.mapper.ts

@@ -1,217 +1,46 @@
-import * as plugins from '../../plugins.js';
+import type * as plugins from '../../plugins.js';
 import type { IIntegrationEntity } from '../../core/types.js';
-import type { ISoundtouchPreset, ISoundtouchSnapshot, ISoundtouchStatus } from './soundtouch.types.js';
+import type { ISoundtouchSnapshot } from './soundtouch.types.js';
 
 export class SoundtouchMapper {
+  public static deviceId(snapshotArg: Pick<ISoundtouchSnapshot, 'homeId' | 'deviceId'>): string {
+    return `soundtouch:${encodeURIComponent(snapshotArg.homeId)}:${snapshotArg.deviceId}`;
+  }
+  public static mediaEntityId(snapshotArg: Pick<ISoundtouchSnapshot, 'homeId' | 'deviceId'>): string { return `${this.deviceId(snapshotArg)}:speaker`; }
   public static toDevices(snapshotArg: ISoundtouchSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
-    const updatedAt = snapshotArg.lastUpdated || new Date().toISOString();
-    const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
-      { id: 'playback', capability: 'media', name: 'Playback', readable: true, writable: true },
-      { id: 'source', capability: 'media', name: 'Source', readable: true, writable: true },
-      { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: true, unit: '%' },
-      { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: true },
-      { id: 'presets', capability: 'media', name: 'Presets', readable: true, writable: true },
-    ];
-    const state: plugins.shxInterfaces.data.IDeviceState[] = [
-      { featureId: 'playback', value: this.mediaState(snapshotArg.status), updatedAt },
-      { featureId: 'source', value: snapshotArg.status?.source || null, updatedAt },
-      { featureId: 'volume', value: typeof snapshotArg.volume?.actual === 'number' ? snapshotArg.volume.actual : null, updatedAt },
-      { featureId: 'muted', value: typeof snapshotArg.volume?.muted === 'boolean' ? snapshotArg.volume.muted : null, updatedAt },
-      { featureId: 'presets', value: snapshotArg.presets?.length || 0, updatedAt },
-    ];
-
-    if (this.mediaTitle(snapshotArg.status)) {
-      features.push({ id: 'current_title', capability: 'media', name: 'Current title', readable: true, writable: false });
-      state.push({ featureId: 'current_title', value: this.mediaTitle(snapshotArg.status) || null, updatedAt });
-    }
-
-    return [{
-      id: this.playerDeviceId(snapshotArg),
-      integrationDomain: 'soundtouch',
-      name: this.deviceName(snapshotArg),
-      protocol: 'http',
-      manufacturer: 'Bose Corporation',
-      model: snapshotArg.config.type,
-      online: snapshotArg.available !== false,
-      features,
-      state,
-      metadata: {
-        deviceId: snapshotArg.config.deviceId,
-        host: snapshotArg.config.host,
-        port: snapshotArg.config.port,
-        macAddress: this.macAddress(snapshotArg),
-        accountUuid: snapshotArg.config.accountUuid,
-        moduleType: snapshotArg.config.moduleType,
-        variant: snapshotArg.config.variant,
-        softwareVersions: snapshotArg.config.components?.map((componentArg) => componentArg.softwareVersion).filter(Boolean),
-      },
+    const settled = snapshotArg.targetVolume === snapshotArg.actualVolume;
+    const optionalCapabilities = snapshotArg.optionalCapabilities.map((capability) => ({ ...capability }));
+    return [{ id: this.deviceId(snapshotArg), integrationDomain: 'soundtouch', name: snapshotArg.displayName ?? snapshotArg.name, manufacturer: 'Bose',
+      protocol: 'http', online: snapshotArg.online,
+      features: [
+        { id: 'connectivity', capability: 'sensor', name: 'Connectivity', readable: true, writable: false },
+        { id: 'identity', capability: 'sensor', name: 'Speaker identity', readable: true, writable: false },
+        { id: 'optional_capabilities', capability: 'sensor', name: 'Declared optional capabilities', readable: true, writable: false },
+        { id: 'target_volume', capability: 'media', name: 'Observed target volume', readable: true, writable: false, unit: 'SoundTouch units' },
+        { id: 'volume', capability: 'media', name: 'Absolute volume', readable: true, writable: settled, unit: 'SoundTouch units' },
+        { id: 'mute', capability: 'media', name: 'Mute', readable: true,
+          writable: settled && snapshotArg.capabilities.mute && snapshotArg.actualVolume <= snapshotArg.volumeLimit },
+      ],
+      state: [
+        { featureId: 'connectivity', value: 'online', updatedAt: snapshotArg.observedAt },
+        { featureId: 'identity', value: { deviceId: snapshotArg.deviceId, type: snapshotArg.type }, updatedAt: snapshotArg.observedAt },
+        { featureId: 'optional_capabilities', value: { capabilities: optionalCapabilities }, updatedAt: snapshotArg.observedAt },
+        { featureId: 'target_volume', value: snapshotArg.targetVolume, updatedAt: snapshotArg.observedAt },
+        { featureId: 'volume', value: snapshotArg.actualVolume, updatedAt: snapshotArg.observedAt },
+        { featureId: 'mute', value: snapshotArg.muted, updatedAt: snapshotArg.observedAt },
+      ],
+      metadata: { homeId: snapshotArg.homeId, deviceId: snapshotArg.deviceId, type: snapshotArg.type, lanAuthenticated: false,
+        observedName: snapshotArg.name, volumeLimit: snapshotArg.volumeLimit, volumeRange: { minimum: 0, maximum: 100, step: 1 },
+        ownerWriteVolumeRange: { minimum: 0, maximum: snapshotArg.volumeLimit, step: 1 },
+        optionalCapabilities, observedAt: snapshotArg.observedAt, standbySupported: false },
     }];
   }
-
   public static toEntities(snapshotArg: ISoundtouchSnapshot): IIntegrationEntity[] {
-    const base = this.entityBase(snapshotArg);
-    const entities: IIntegrationEntity[] = [{
-      id: `media_player.${base}`,
-      uniqueId: `soundtouch_${this.uniqueBase(snapshotArg)}`,
-      integrationDomain: 'soundtouch',
-      deviceId: this.playerDeviceId(snapshotArg),
-      platform: 'media_player',
-      name: this.deviceName(snapshotArg),
-      state: this.mediaState(snapshotArg.status),
-      attributes: {
-        deviceClass: 'speaker',
-        deviceId: snapshotArg.config.deviceId,
-        model: snapshotArg.config.type,
-        macAddress: this.macAddress(snapshotArg),
-        volumeLevel: typeof snapshotArg.volume?.actual === 'number' ? Math.max(0, Math.min(1, snapshotArg.volume.actual / 100)) : undefined,
-        volume: snapshotArg.volume?.actual,
-        targetVolume: snapshotArg.volume?.target,
-        isVolumeMuted: snapshotArg.volume?.muted,
-        source: snapshotArg.status?.source,
-        sourceList: snapshotArg.sourceList || [],
-        presetList: this.presetList(snapshotArg),
-        mediaContentType: snapshotArg.status?.contentItem?.type || snapshotArg.status?.streamType,
-        mediaContentId: snapshotArg.status?.contentItem?.location || snapshotArg.status?.trackId,
-        mediaTitle: this.mediaTitle(snapshotArg.status),
-        mediaArtist: snapshotArg.status?.artist,
-        mediaTrack: snapshotArg.status?.track,
-        mediaAlbumName: snapshotArg.status?.album,
-        mediaImageUrl: snapshotArg.status?.image,
-        mediaDuration: snapshotArg.status?.duration,
-        mediaPosition: snapshotArg.status?.position,
-        shuffle: snapshotArg.status?.shuffleSetting,
-        repeat: snapshotArg.status?.repeatSetting,
-        stationName: snapshotArg.status?.stationName,
-        stationLocation: snapshotArg.status?.stationLocation,
-        soundtouchZone: this.zoneAttribute(snapshotArg),
-        soundtouchGroup: this.groupAttribute(snapshotArg),
-      },
-      available: snapshotArg.available !== false,
+    return [{ id: this.mediaEntityId(snapshotArg), uniqueId: this.mediaEntityId(snapshotArg), deviceId: this.deviceId(snapshotArg),
+      integrationDomain: 'soundtouch', platform: 'media_player', name: snapshotArg.displayName ?? snapshotArg.name, state: 'unknown', available: snapshotArg.online,
+      attributes: { type: snapshotArg.type, volume: snapshotArg.actualVolume, targetVolume: snapshotArg.targetVolume, muted: snapshotArg.muted,
+        volumeLimit: snapshotArg.volumeLimit, optionalCapabilities: snapshotArg.optionalCapabilities.map((capability) => ({ ...capability })),
+        observedAt: snapshotArg.observedAt, standbySupported: false },
     }];
-
-    entities.push({
-      id: `sensor.${base}_soundtouch_presets`,
-      uniqueId: `soundtouch_${this.uniqueBase(snapshotArg)}_presets`,
-      integrationDomain: 'soundtouch',
-      deviceId: this.playerDeviceId(snapshotArg),
-      platform: 'sensor',
-      name: `${this.deviceName(snapshotArg)} SoundTouch Presets`,
-      state: snapshotArg.presets?.length || 0,
-      attributes: { presets: this.presetList(snapshotArg) },
-      available: snapshotArg.available !== false,
-    });
-
-    entities.push({
-      id: `sensor.${base}_soundtouch_sources`,
-      uniqueId: `soundtouch_${this.uniqueBase(snapshotArg)}_sources`,
-      integrationDomain: 'soundtouch',
-      deviceId: this.playerDeviceId(snapshotArg),
-      platform: 'sensor',
-      name: `${this.deviceName(snapshotArg)} SoundTouch Sources`,
-      state: snapshotArg.sourceList?.length || 0,
-      attributes: { sourceList: snapshotArg.sourceList || [] },
-      available: snapshotArg.available !== false,
-    });
-
-    entities.push({
-      id: `sensor.${base}_soundtouch_media`,
-      uniqueId: `soundtouch_${this.uniqueBase(snapshotArg)}_media`,
-      integrationDomain: 'soundtouch',
-      deviceId: this.playerDeviceId(snapshotArg),
-      platform: 'sensor',
-      name: `${this.deviceName(snapshotArg)} SoundTouch Media`,
-      state: this.mediaTitle(snapshotArg.status) || snapshotArg.status?.source || 'None',
-      attributes: { status: snapshotArg.status },
-      available: snapshotArg.available !== false,
-    });
-
-    return entities;
-  }
-
-  public static playerDeviceId(snapshotArg: ISoundtouchSnapshot): string {
-    return `soundtouch.player.${this.uniqueBase(snapshotArg)}`;
-  }
-
-  public static slug(valueArg: string | undefined): string {
-    return (valueArg || 'soundtouch').toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'soundtouch';
-  }
-
-  private static mediaState(statusArg: ISoundtouchStatus | undefined): string {
-    if (!statusArg || statusArg.source === 'STANDBY' || statusArg.playStatus === 'STOP_STATE') {
-      return 'off';
-    }
-    if (statusArg.source === 'INVALID_SOURCE') {
-      return 'unknown';
-    }
-    if (statusArg.playStatus === 'PLAY_STATE' || statusArg.playStatus === 'BUFFERING_STATE') {
-      return 'playing';
-    }
-    if (statusArg.playStatus === 'PAUSE_STATE') {
-      return 'paused';
-    }
-    return 'idle';
-  }
-
-  private static mediaTitle(statusArg: ISoundtouchStatus | undefined): string | undefined {
-    if (!statusArg) {
-      return undefined;
-    }
-    if (statusArg.stationName) {
-      return statusArg.stationName;
-    }
-    if (statusArg.artist && statusArg.track) {
-      return `${statusArg.artist} - ${statusArg.track}`;
-    }
-    return statusArg.track || statusArg.contentItem?.name || statusArg.description;
-  }
-
-  private static presetList(snapshotArg: ISoundtouchSnapshot): Array<Record<string, unknown>> {
-    return (snapshotArg.presets || []).map((presetArg: ISoundtouchPreset) => ({
-      presetId: presetArg.presetId,
-      name: presetArg.name,
-      source: presetArg.source,
-      type: presetArg.type,
-      location: presetArg.location,
-      sourceAccount: presetArg.sourceAccount,
-      isPresetable: presetArg.isPresetable,
-    }));
-  }
-
-  private static zoneAttribute(snapshotArg: ISoundtouchSnapshot): Record<string, unknown> | undefined {
-    if (!snapshotArg.zone) {
-      return undefined;
-    }
-    return {
-      master: snapshotArg.zone.masterId,
-      masterIp: snapshotArg.zone.masterIp,
-      isMaster: snapshotArg.zone.isMaster,
-      slaves: snapshotArg.zone.slaves,
-    };
-  }
-
-  private static groupAttribute(snapshotArg: ISoundtouchSnapshot): string[] | undefined {
-    if (!snapshotArg.zone) {
-      return undefined;
-    }
-    return [
-      snapshotArg.zone.masterId || snapshotArg.zone.masterIp,
-      ...snapshotArg.zone.slaves.map((slaveArg) => slaveArg.deviceId || slaveArg.ipAddress),
-    ].filter((valueArg): valueArg is string => Boolean(valueArg));
-  }
-
-  private static deviceName(snapshotArg: ISoundtouchSnapshot): string {
-    return snapshotArg.config.name || snapshotArg.config.type || 'Bose SoundTouch';
-  }
-
-  private static entityBase(snapshotArg: ISoundtouchSnapshot): string {
-    return this.slug(this.deviceName(snapshotArg));
-  }
-
-  private static uniqueBase(snapshotArg: ISoundtouchSnapshot): string {
-    return this.slug(snapshotArg.config.deviceId || this.macAddress(snapshotArg) || snapshotArg.config.host || this.deviceName(snapshotArg));
-  }
-
-  private static macAddress(snapshotArg: ISoundtouchSnapshot): string | undefined {
-    return snapshotArg.config.networks?.find((networkArg) => networkArg.type === 'SMSC')?.macAddress || snapshotArg.config.networks?.[0]?.macAddress;
   }
 }

package/ts/integrations/soundtouch/soundtouch.types.ts

@@ -1,199 +1,54 @@
-export const soundtouchDefaultPort = 8090;
-export const soundtouchDefaultDlnaPort = 8091;
-export const soundtouchDefaultSourceList = ['AUX', 'BLUETOOTH'] as const;
-
-export type TSoundtouchPlayStatus = 'PLAY_STATE' | 'BUFFERING_STATE' | 'PAUSE_STATE' | 'STOP_STATE' | string;
-
-export type TSoundtouchSource =
-  | 'SLAVE_SOURCE'
-  | 'INTERNET_RADIO'
-  | 'PANDORA'
-  | 'AIRPLAY'
-  | 'STORED_MUSIC'
-  | 'AUX'
-  | 'OFF_SOURCE'
-  | 'CURRATED_RADIO'
-  | 'STANDBY'
-  | 'UPDATE'
-  | 'DEEZER'
-  | 'SPOTIFY'
-  | 'IHEART'
-  | 'LOCAL_MUSIC'
-  | 'BLUETOOTH'
-  | 'INVALID_SOURCE'
-  | string;
-
-export type TSoundtouchContentType = 'uri' | 'track' | 'album' | 'playlist' | string;
-
-export type TSoundtouchCommand =
-  | 'turn_on'
-  | 'turn_off'
-  | 'play'
-  | 'pause'
-  | 'play_pause'
-  | 'previous_track'
-  | 'next_track'
-  | 'volume_up'
-  | 'volume_down'
-  | 'set_volume'
-  | 'mute'
-  | 'select_source'
-  | 'play_media'
-  | 'play_preset';
+import type * as plugins from '../../plugins.js';
+import type { INativeConfigFlowContext, INativeIntegrationSetupContext } from '../../core/types.js';
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
 
+export const soundtouchDomain = 'soundtouch';
+export const soundtouchDefaultPort = 8090;
+export const soundtouchDefaultTimeoutMs = 5000;
+export interface ISoundtouchHomeOptions extends INativeIntegrationOwnerOptions {}
+export interface ISoundtouchSetupContext extends INativeIntegrationSetupContext {}
+export interface ISoundtouchConfigFlowContext extends INativeConfigFlowContext {}
 export interface ISoundtouchConfig {
-  host?: string;
-  port?: number;
-  dlnaPort?: number;
-  name?: string;
-  deviceId?: string;
-  model?: string;
-  macAddress?: string;
-  sourceList?: string[];
-  timeoutMs?: number;
-  snapshot?: ISoundtouchSnapshot;
-  commandExecutor?: ISoundtouchCommandExecutor;
+  readonly homeId: string;
+  readonly host: string;
+  /** Exact uppercase unicast deviceID previously observed on the selected device. */
+  readonly deviceId: string;
+  /** Documented /info type; the protocol supplies no model field. */
+  readonly type: string;
+  readonly allowUnencryptedLan: true;
+  /** Owner's absolute integer volume ceiling, 0–100. */
+  readonly volumeLimit: number;
+  readonly port?: number;
+  /** Optional local display label; observed /info name remains in the snapshot. */
+  readonly name?: string;
+  readonly requestTimeoutMs?: number;
+  readonly maxPendingOperations?: number;
+  readonly maxResponseBytes?: number;
 }
-
 export interface IHomeAssistantSoundtouchConfig extends ISoundtouchConfig {}
-
-export interface ISoundtouchCommandExecutor {
-  execute(requestArg: ISoundtouchRawCommandRequest): Promise<unknown>;
-}
-
-export interface ISoundtouchRawCommandRequest {
-  command: TSoundtouchCommand | 'refresh';
-  method: 'GET' | 'POST';
-  path: string;
-  url: string;
-  host?: string;
-  port: number;
-  body?: string;
-  headers?: Record<string, string>;
-}
-
-export interface ISoundtouchCommandRequest {
-  command: TSoundtouchCommand;
-  source?: string;
-  presetId?: string;
-  presetName?: string;
-  mediaId?: string;
-  mediaType?: string;
-  url?: string;
-  volumeLevel?: number;
-  volume?: number;
-  muted?: boolean;
-  contentItem?: ISoundtouchContentItem;
-}
-
-export interface ISoundtouchSnapshot {
-  config: ISoundtouchDeviceInfo;
-  status?: ISoundtouchStatus;
-  volume?: ISoundtouchVolume;
-  presets?: ISoundtouchPreset[];
-  zone?: ISoundtouchZoneStatus;
-  sourceList?: string[];
-  available?: boolean;
-  lastUpdated?: string;
-  error?: string;
-}
-
-export interface ISoundtouchDeviceInfo {
-  deviceId?: string;
-  name?: string;
-  type?: string;
-  accountUuid?: string;
-  moduleType?: string;
-  variant?: string;
-  variantMode?: string;
-  countryCode?: string;
-  regionCode?: string;
-  host?: string;
-  port?: number;
-  networks?: ISoundtouchNetworkInfo[];
-  components?: ISoundtouchComponentInfo[];
-}
-
-export interface ISoundtouchNetworkInfo {
-  type?: string;
-  macAddress?: string;
-  ipAddress?: string;
-}
-
-export interface ISoundtouchComponentInfo {
-  category?: string;
-  softwareVersion?: string;
-  serialNumber?: string;
-}
-
-export interface ISoundtouchContentItem {
-  name?: string;
-  source?: TSoundtouchSource;
-  type?: TSoundtouchContentType;
-  location?: string;
-  sourceAccount?: string;
-  isPresetable?: boolean;
-}
-
-export interface ISoundtouchStatus {
-  source?: TSoundtouchSource;
-  contentItem?: ISoundtouchContentItem;
-  track?: string;
-  artist?: string;
-  album?: string;
-  image?: string;
-  duration?: number;
-  position?: number;
-  playStatus?: TSoundtouchPlayStatus;
-  shuffleSetting?: string;
-  repeatSetting?: string;
-  streamType?: string;
-  trackId?: string;
-  stationName?: string;
-  description?: string;
-  stationLocation?: string;
-}
-
-export interface ISoundtouchVolume {
-  actual?: number;
-  target?: number;
-  muted?: boolean;
-}
-
-export interface ISoundtouchPreset extends ISoundtouchContentItem {
-  presetId: string;
-  sourceXml?: string;
-}
-
-export interface ISoundtouchZoneStatus {
-  masterId?: string;
-  masterIp?: string;
-  isMaster?: boolean;
-  slaves: ISoundtouchZoneMember[];
-}
-
-export interface ISoundtouchZoneMember {
-  deviceId?: string;
-  ipAddress?: string;
-  role?: string;
-}
-
-export interface ISoundtouchMdnsRecord {
-  name?: string;
-  type?: string;
-  host?: string;
-  port?: number;
-  txt?: Record<string, string | undefined>;
-}
-
-export interface ISoundtouchManualEntry {
-  host?: string;
-  port?: number;
-  id?: string;
-  name?: string;
-  manufacturer?: string;
-  model?: string;
-  deviceId?: string;
-  macAddress?: string;
-  metadata?: Record<string, unknown>;
-}
+export interface ISoundtouchSnapshot extends plugins.ecobridgeDeviceManager.IBoseSoundTouchState {
+  readonly homeId: string;
+  readonly displayName?: string;
+  readonly volumeLimit: number;
+  readonly online: true;
+}
+export type TSoundtouchRawData = ISoundtouchSnapshot;
+export type TSoundtouchClientEvent =
+  | { readonly type: 'snapshot'; readonly snapshot: ISoundtouchSnapshot }
+  | { readonly type: 'control'; readonly observation: plugins.ecobridgeDeviceManager.IBoseSoundTouchControlResult }
+  | { readonly type: 'error'; readonly error: Error };
+export const soundtouchProfile = {
+  domain: soundtouchDomain, displayName: 'Bose SoundTouch', status: 'control-runtime',
+  metadata: {
+    source: 'home-assistant/core', upstreamDomain: soundtouchDomain, configFlow: true,
+    localApi: {
+      status: 'Selected native SoundTouch HTTP/XML through devicemanager.',
+      implemented: ['exact selected home/private IPv4/deviceID/type binding', 'live sanitized identity, optional capability declarations and actual volume/mute',
+        'fresh settled-volume admission and owner-bounded absolute volume/mute', 'status acknowledgment and independent state observation without causal claims',
+        'caller-owned optional home/domain config store', 'explicit observation events and joined terminal cleanup'],
+      explicitUnsupported: ['automatic discovery', 'cloud access or fallback', 'injected clients, snapshots and executors',
+        'power, standby, key/toggle/increment, source, preset, media and zone controls', 'defined command-success vocabulary',
+        'automatic retry, replay, reconnect or push subscription', 'cryptographic LAN peer authentication'],
+    },
+  },
+} as const;

package/ts/integrations/soundtouch/soundtouch.validation.ts

@@ -0,0 +1,60 @@
+import * as plugins from '../../plugins.js';
+import type { ISoundtouchConfig } from './soundtouch.types.js';
+import { soundtouchDefaultPort, soundtouchDefaultTimeoutMs } from './soundtouch.types.js';
+
+export function soundtouchRecord(valueArg: unknown, nameArg: string): Record<string, unknown> {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) throw new TypeError(`SoundTouch ${nameArg} must be a plain data object.`);
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError(`SoundTouch ${nameArg} may not contain symbols, accessors or hidden fields.`);
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+export function soundtouchKeys(valueArg: Record<string, unknown>, keysArg: readonly string[]): void {
+  if (Object.keys(valueArg).some((key) => !keysArg.includes(key))) throw new TypeError('SoundTouch data contains unsupported fields.');
+}
+export function soundtouchText(valueArg: unknown, nameArg: string, maximumArg = 128): string {
+  if (typeof valueArg !== 'string' || !valueArg.trim() || valueArg.length > maximumArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`SoundTouch ${nameArg} must be a non-empty string without control characters, at most ${maximumArg} characters.`);
+  }
+  return valueArg;
+}
+export function soundtouchInteger(valueArg: unknown, minimumArg: number, maximumArg: number, nameArg: string): number {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new RangeError(`SoundTouch ${nameArg} must be an integer from ${minimumArg} through ${maximumArg}.`);
+  }
+  return valueArg;
+}
+export function soundtouchBoolean(valueArg: unknown): boolean {
+  if (typeof valueArg !== 'boolean') throw new TypeError('SoundTouch mute requires an explicit boolean.');
+  return valueArg;
+}
+export function readSoundtouchEndpoint(hostArg: unknown, idArg: unknown, typeArg: unknown, portArg?: unknown): Pick<ISoundtouchConfig, 'host' | 'deviceId' | 'type'> & { port: number } {
+  if (typeof hostArg !== 'string' || plugins.net.isIP(hostArg) !== 4) throw new TypeError('SoundTouch host must be a selected private IPv4 address.');
+  const [first, second, , last] = hostArg.split('.').map(Number);
+  if (!(first === 10 || first === 127 || first === 192 && second === 168 || first === 172 && second >= 16 && second <= 31)
+    || last === 0 || last === 255) throw new TypeError('SoundTouch host must be a selected private or loopback unicast IPv4 address.');
+  if (typeof idArg !== 'string' || !/^[0-9A-F]{12}$/.test(idArg) || /^(0{12}|F{12})$/.test(idArg)
+    || (Number.parseInt(idArg.slice(0, 2), 16) & 1) !== 0) throw new TypeError('SoundTouch deviceId must be the exact uppercase unicast twelve-digit deviceID.');
+  return { host: hostArg, deviceId: idArg, type: soundtouchText(typeArg, 'selected type'),
+    port: soundtouchInteger(portArg === undefined ? soundtouchDefaultPort : portArg, 1, 65535, 'port') };
+}
+export function normalizeSoundtouchConfig(valueArg: unknown) {
+  const values = soundtouchRecord(valueArg, 'configuration');
+  soundtouchKeys(values, ['homeId', 'host', 'deviceId', 'type', 'allowUnencryptedLan', 'volumeLimit', 'port', 'name',
+    'requestTimeoutMs', 'maxPendingOperations', 'maxResponseBytes']);
+  if (values.allowUnencryptedLan !== true) throw new TypeError('SoundTouch requires explicit allowUnencryptedLan: true admission.');
+  return Object.freeze({ homeId: soundtouchText(values.homeId, 'homeId', 256),
+    ...readSoundtouchEndpoint(values.host, values.deviceId, values.type, values.port), allowUnencryptedLan: true as const,
+    volumeLimit: soundtouchInteger(values.volumeLimit, 0, 100, 'volumeLimit'),
+    ...(values.name === undefined ? {} : { name: soundtouchText(values.name, 'name') }),
+    requestTimeoutMs: soundtouchInteger(values.requestTimeoutMs === undefined ? soundtouchDefaultTimeoutMs : values.requestTimeoutMs, 1, 30000, 'requestTimeoutMs'),
+    maxPendingOperations: soundtouchInteger(values.maxPendingOperations === undefined ? 16 : values.maxPendingOperations, 1, 128, 'maxPendingOperations'),
+    maxResponseBytes: soundtouchInteger(values.maxResponseBytes === undefined ? 16384 : values.maxResponseBytes, 256, 65536, 'maxResponseBytes'),
+  });
+}

package/ts/integrations/wiz/index.ts

@@ -4,3 +4,4 @@ export * from './wiz.classes.integration.js';
 export * from './wiz.discovery.js';
 export * from './wiz.mapper.js';
 export * from './wiz.types.js';
+export * from './wiz.validation.js';