@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/sonos/sonos.classes.integration.ts

@@ -1,11 +1,12 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { SonosClient } from './sonos.classes.client.js';
 import { SonosConfigFlow } from './sonos.classes.configflow.js';
 import { createSonosDiscoveryDescriptor } from './sonos.discovery.js';
 import { SonosMapper } from './sonos.mapper.js';
-import type { ISonosConfig } from './sonos.types.js';
+import { isSonosDataRecord } from './sonos.config.js';
+import type { ISonosConfig, ISonosSnapshot } from './sonos.types.js';
 
 export class SonosIntegration extends BaseIntegration<ISonosConfig> {
   public readonly domain = 'sonos';
@@ -13,93 +14,254 @@ export class SonosIntegration extends BaseIntegration<ISonosConfig> {
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createSonosDiscoveryDescriptor();
   public readonly configFlow = new SonosConfigFlow();
-  public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/sonos',
-    upstreamDomain: 'sonos',
-    integrationType: 'hub',
-    iotClass: 'local_push',
-    qualityScale: 'bronze',
-  };
-
-  public async setup(configArg: ISonosConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new SonosRuntime(new SonosClient(configArg));
+  public readonly metadata = { source: 'native-typescript', integrationType: 'device', iotClass: 'local_poll' };
+  private readonly runtimes = new Set<SonosRuntime>();
+  private readonly setups = new Set<Promise<IIntegrationRuntime>>();
+  private readonly lifetime = new AbortController();
+  private closePromise?: Promise<void>;
+
+  public setup(config: ISonosConfig, context: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    if (this.lifetime.signal.aborted) return Promise.reject(new Error('Sonos integration is closed.'));
+    const signal = AbortSignal.any([this.lifetime.signal, ...(context.abortSignal ? [context.abortSignal] : [])]);
+    const pending = (async () => {
+      const client = new SonosClient(config, signal);
+      try {
+        const initial = await client.getSnapshot(signal);
+        signal.throwIfAborted();
+        const runtime = new SonosRuntime(client, initial, { ...context, abortSignal: signal }, () => { this.runtimes.delete(runtime); });
+        this.runtimes.add(runtime);
+        return runtime;
+      } catch (error) {
+        try { await client.destroy(); }
+        catch (cleanupError) { throw new AggregateError([error, cleanupError], 'Sonos setup and cleanup failed.'); }
+        throw error;
+      }
+    })();
+    this.setups.add(pending);
+    void pending.then(() => this.setups.delete(pending), () => this.setups.delete(pending));
+    return pending;
   }
 
-  public async destroy(): Promise<void> {}
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.lifetime.abort(new Error('Sonos integration is closed.'));
+      this.closePromise = (async () => {
+        await Promise.allSettled([...this.setups]);
+        const results = await Promise.allSettled([...this.runtimes].map((runtime) => runtime.destroy()));
+        this.runtimes.clear();
+        const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+        if (failures.length) throw new AggregateError(failures.map((result) => result.reason), 'Sonos runtime cleanup failed.');
+      })();
+    }
+    return this.closePromise;
+  }
 }
 
 export class HomeAssistantSonosIntegration extends SonosIntegration {}
 
+interface ISonosSubscription {
+  controller: AbortController;
+  job: Promise<void>;
+  failed: boolean;
+  failure?: unknown;
+  stop(): Promise<void>;
+}
+
 class SonosRuntime implements IIntegrationRuntime {
-  public domain = 'sonos';
+  public readonly domain = 'sonos';
+  private readonly lifetime = new AbortController();
+  private readonly subscriptions = new Set<ISonosSubscription>();
+  private healthy = true;
+  private closed = false;
+  private closePromise?: Promise<void>;
+  private readonly parentAbort?: () => void;
 
-  constructor(private readonly client: SonosClient) {}
+  constructor(private readonly client: SonosClient, private snapshot: ISonosSnapshot, private readonly context: IIntegrationSetupContext = {}, private readonly onClosed?: () => void) {
+    if (context.abortSignal) {
+      this.parentAbort = () => this.lifetime.abort(context.abortSignal?.reason);
+      context.abortSignal.addEventListener('abort', this.parentAbort, { once: true });
+      if (context.abortSignal.aborted) this.parentAbort();
+    }
+  }
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return SonosMapper.toDevices(await this.client.getSnapshot());
+  public isHealthy(): boolean { return this.healthy && !this.closed && !this.lifetime.signal.aborted; }
+
+  public async devices(signal?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return SonosMapper.toDevices(await this.read(signal));
   }
 
-  public async entities(): Promise<IIntegrationEntity[]> {
-    return SonosMapper.toEntities(await this.client.getSnapshot());
+  public async entities(): Promise<IIntegrationEntity[]> { return SonosMapper.toEntities(await this.read()); }
+
+  public async writeFeature(request: IDeviceFeatureWriteRequest, signal?: AbortSignal): Promise<IServiceCallResult> {
+    assertDataRecord(request, ['device', 'feature', 'value']);
+    assertDataRecord(request.device);
+    assertDataRecord(request.feature);
+    const deviceId = request.device.id;
+    const integrationDomain = request.device.integrationDomain;
+    const featureId = request.feature.id;
+    const value = request.value;
+    const snapshot = await this.read(signal);
+    const device = SonosMapper.toDevices(snapshot)[0];
+    if (integrationDomain !== this.domain || deviceId !== device.id) throw new Error('Sonos feature target does not belong to the selected renderer.');
+    const feature = device.features.find((feature) => feature.id === featureId);
+    if (!feature?.writable || feature.capability !== 'media') throw new Error('Sonos feature is not writable for this renderer.');
+    if (feature.id === 'volume') {
+      if (typeof value !== 'number') throw new Error('Sonos volume must be numeric.');
+      await this.client.setVolume(value, this.signal(signal));
+    } else if (feature.id === 'muted') {
+      if (typeof value !== 'boolean') throw new Error('Sonos mute must be boolean.');
+      await this.client.setMute(value, this.signal(signal));
+    } else if (feature.id === 'playback') {
+      if (value === 'playing') await this.client.play(this.signal(signal));
+      else if (value === 'paused') await this.client.pause(this.signal(signal));
+      else if (value === 'stopped') await this.client.stop(this.signal(signal));
+      else throw new Error('Sonos playback must be playing, paused or stopped.');
+    } else throw new Error('Unsupported Sonos feature.');
+    return this.readback(signal);
   }
 
-  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.domain !== 'media_player') {
-      return { success: false, error: `Unsupported Sonos service domain: ${requestArg.domain}` };
-    }
+  public async callService(request: IServiceCallRequest): Promise<IServiceCallResult> {
+    assertDataRecord(request, ['domain', 'service', 'target', 'data']);
+    assertDataRecord(request.target, ['deviceId', 'entityId']);
+    if (request.data !== undefined) assertDataRecord(request.data);
+    request = { domain: request.domain, service: request.service,
+      target: { ...(request.target.deviceId === undefined ? {} : { deviceId: request.target.deviceId }),
+        ...(request.target.entityId === undefined ? {} : { entityId: request.target.entityId }) },
+      ...(request.data === undefined ? {} : { data: { ...request.data } }) };
+    if (request.domain !== 'media_player' || typeof request.service !== 'string') throw new Error('Unsupported Sonos service domain.');
+    const snapshot = await this.read();
+    const deviceId = SonosMapper.deviceId(snapshot);
+    const entityId = SonosMapper.entityId(snapshot.speakerInfo.uid);
+    if ((!request.target.deviceId && !request.target.entityId) || (request.target.deviceId !== undefined && request.target.deviceId !== deviceId)
+      || (request.target.entityId !== undefined && request.target.entityId !== entityId)) throw new Error('Sonos service target does not belong to the selected renderer.');
+    const data = request.data ?? {};
+    assertDataRecord(data);
+    const signal = this.signal();
+    if (['play', 'pause', 'stop', 'next_track', 'previous_track'].includes(request.service)) {
+      assertDataRecord(data, []);
+      if (request.service === 'play') await this.client.play(signal);
+      else if (request.service === 'pause') await this.client.pause(signal);
+      else if (request.service === 'stop') await this.client.stop(signal);
+      else if (request.service === 'next_track') await this.client.next(signal);
+      else await this.client.previous(signal);
+    } else if (request.service === 'volume_set') {
+      assertDataRecord(data, ['volume', 'volume_level']);
+      if (Object.hasOwn(data, 'volume') === Object.hasOwn(data, 'volume_level')) throw new Error('Sonos volume_set requires exactly one volume argument.');
+      const value = Object.hasOwn(data, 'volume') ? data.volume : data.volume_level;
+      if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error('Sonos volume must be finite.');
+      const percent = Math.round(value * 100);
+      if (Object.hasOwn(data, 'volume_level') && (value < 0 || value > 1 || Math.abs(value * 100 - percent) > 1e-8)) throw new Error('Sonos volume_level must represent an integer percent from 0 to 100.');
+      await this.client.setVolume(Object.hasOwn(data, 'volume') ? value : percent, signal);
+    } else if (request.service === 'volume_mute') {
+      assertDataRecord(data, ['muted', 'is_volume_muted']);
+      if (Object.hasOwn(data, 'muted') === Object.hasOwn(data, 'is_volume_muted')) throw new Error('Sonos volume_mute requires exactly one mute argument.');
+      const value = Object.hasOwn(data, 'muted') ? data.muted : data.is_volume_muted;
+      if (typeof value !== 'boolean') throw new Error('Sonos mute must be boolean.');
+      await this.client.setMute(value, signal);
+    } else if (request.service === 'play_media') {
+      assertDataRecord(data, ['uri', 'media_content_id', 'title', 'mime_type']);
+      if (Object.hasOwn(data, 'uri') === Object.hasOwn(data, 'media_content_id')) throw new Error('Sonos play_media requires exactly one URI argument.');
+      const uri = Object.hasOwn(data, 'uri') ? data.uri : data.media_content_id;
+      if (typeof uri !== 'string' || (data.title !== undefined && typeof data.title !== 'string') || (data.mime_type !== undefined && typeof data.mime_type !== 'string')) throw new Error('Sonos media URI, title and MIME type must be text.');
+      await this.client.playUri(uri, { title: data.title, mimeType: data.mime_type }, signal);
+    } else throw new Error(`Unsupported Sonos service: ${request.service}`);
+    return this.readback();
+  }
 
-    if (requestArg.service === 'play') {
-      await this.client.play();
-      return { success: true };
-    }
-    if (requestArg.service === 'pause') {
-      await this.client.pause();
-      return { success: true };
-    }
-    if (requestArg.service === 'stop') {
-      await this.client.stop();
-      return { success: true };
-    }
-    if (requestArg.service === 'next_track') {
-      await this.client.next();
-      return { success: true };
-    }
-    if (requestArg.service === 'previous_track') {
-      await this.client.previous();
-      return { success: true };
-    }
-    if (requestArg.service === 'volume_set') {
-      const rawVolume = requestArg.data?.volume_level ?? requestArg.data?.volume;
-      const volume = typeof rawVolume === 'number' && rawVolume <= 1 ? rawVolume * 100 : rawVolume;
-      if (typeof volume !== 'number') {
-        return { success: false, error: 'Sonos volume_set requires data.volume_level or data.volume.' };
-      }
-      await this.client.setVolume(volume);
-      return { success: true };
-    }
-    if (requestArg.service === 'volume_mute') {
-      const muted = requestArg.data?.is_volume_muted ?? requestArg.data?.muted;
-      if (typeof muted !== 'boolean') {
-        return { success: false, error: 'Sonos volume_mute requires data.is_volume_muted or data.muted.' };
-      }
-      await this.client.setMute(muted);
-      return { success: true };
-    }
-    if (requestArg.service === 'play_media') {
-      const uri = requestArg.data?.media_content_id ?? requestArg.data?.uri;
-      if (typeof uri !== 'string' || !uri) {
-        return { success: false, error: 'Sonos play_media requires data.media_content_id or data.uri.' };
+  public async subscribe(handler: (event: IIntegrationEvent) => void, signal?: AbortSignal): Promise<() => Promise<void>> {
+    if (typeof handler !== 'function') throw new Error('Sonos subscription handler must be callable.');
+    if (this.subscriptions.size >= 16) throw new Error('Sonos runtime supports at most 16 subscriptions.');
+    const controller = new AbortController();
+    const combined = AbortSignal.any([this.signal(signal), controller.signal]);
+    const initial = await this.read(combined);
+    combined.throwIfAborted();
+    if (this.subscriptions.size >= 16) throw new Error('Sonos runtime supports at most 16 subscriptions.');
+    handler(this.event('state_changed', initial));
+    combined.throwIfAborted();
+    let subscription: ISonosSubscription;
+    const job = (async () => {
+      while (!combined.aborted) {
+        await wait(this.client.config.pollIntervalMs, combined);
+        if (combined.aborted) return;
+        let snapshot: ISonosSnapshot;
+        try { snapshot = await this.read(combined); }
+        catch (error) {
+          if (combined.aborted) return;
+          handler(this.event('availability_changed', { available: false }));
+          handler(this.event('error', { message: error instanceof Error ? error.message : 'Sonos read failed.' }));
+          continue;
+        }
+        handler(this.event('state_changed', snapshot));
       }
-      await this.client.playUri(uri, typeof requestArg.data?.title === 'string' ? requestArg.data.title : undefined);
-      return { success: true };
+    })().catch((error: unknown) => {
+      if (!combined.aborted) { subscription.failed = true; subscription.failure = error; this.healthy = false; controller.abort(error); }
+    }).then(() => {
+      if (!subscription.failed) this.subscriptions.delete(subscription);
+    });
+    subscription = {
+      controller, job, failed: false,
+      stop: async () => {
+        controller.abort(new Error('Sonos subscription stopped.'));
+        await job;
+        this.subscriptions.delete(subscription);
+        if (subscription.failed) throw subscription.failure;
+      },
+    };
+    this.subscriptions.add(subscription);
+    return subscription.stop;
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.closed = true;
+      this.healthy = false;
+      this.lifetime.abort(new Error('Sonos runtime is closed.'));
+      if (this.parentAbort) this.context.abortSignal?.removeEventListener('abort', this.parentAbort);
+      this.closePromise = (async () => {
+        const results = await Promise.allSettled([this.client.destroy(), ...[...this.subscriptions].map((subscription) => subscription.stop())]);
+        this.onClosed?.();
+        const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+        if (failures.length) throw new AggregateError(failures.map((result) => result.reason), 'Sonos cleanup failed.');
+      })();
     }
+    return this.closePromise;
+  }
 
-    return { success: false, error: `Unsupported Sonos media_player service: ${requestArg.service}` };
+  private async read(signal?: AbortSignal): Promise<ISonosSnapshot> {
+    try { this.snapshot = await this.client.getSnapshot(this.signal(signal)); this.healthy = true; return this.snapshot; }
+    catch (error) { this.healthy = false; throw error; }
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+  private async readback(signal?: AbortSignal): Promise<IServiceCallResult> {
+    const snapshot = await this.read(signal);
+    return { success: true, data: { devices: SonosMapper.toDevices(snapshot), entities: SonosMapper.toEntities(snapshot) } };
   }
+
+  private signal(signal?: AbortSignal): AbortSignal {
+    const combined = AbortSignal.any([this.lifetime.signal, ...(signal ? [signal] : [])]);
+    combined.throwIfAborted();
+    return combined;
+  }
+
+  private event(type: IIntegrationEvent['type'], data: unknown): IIntegrationEvent {
+    return { type, integrationDomain: this.domain, deviceId: SonosMapper.deviceId(this.snapshot),
+      entityId: SonosMapper.entityId(this.snapshot.speakerInfo.uid), data: structuredClone(data), timestamp: Date.now() };
+  }
+}
+
+function assertDataRecord(value: unknown, allowed?: string[]): asserts value is Record<string, unknown> {
+  if (!isSonosDataRecord(value)) throw new Error('Sonos input must be a plain object.');
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== 'string' || !descriptor || !('value' in descriptor) || (allowed && !allowed.includes(key))) throw new Error('Sonos input contains an unsupported field.');
+  }
+}
+
+function wait(milliseconds: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const finish = (): void => { clearTimeout(timer); signal.removeEventListener('abort', finish); resolve(); };
+    const timer = setTimeout(finish, milliseconds);
+    signal.addEventListener('abort', finish, { once: true });
+    if (signal.aborted) finish();
+  });
 }

package/ts/integrations/sonos/sonos.classes.ssdpprobe.ts

@@ -0,0 +1,85 @@
+import * as plugins from '../../plugins.js';
+import type { IDiscoveryCandidate, IDiscoveryContext, IDiscoveryProbe, IDiscoveryProbeResult } from '../../core/types.js';
+import { SonosSsdpMatcher } from './sonos.matchers.js';
+
+export interface ISonosSsdpProbeOptions {
+  scanDurationMs?: number;
+  startupTimeoutMs?: number;
+  dependencies?: plugins.ecobridgeDeviceManager.ISsdpDiscoveryDependencies;
+}
+
+export class SonosSsdpProbe implements IDiscoveryProbe {
+  public readonly id = 'sonos-ssdp-probe';
+  public readonly source = 'ssdp' as const;
+  public readonly description = 'Discover local Sonos ZonePlayers through the owning native SSDP client.';
+  private readonly scanDurationMs: number;
+  private readonly startupTimeoutMs: number;
+  private readonly dependencies: plugins.ecobridgeDeviceManager.ISsdpDiscoveryDependencies;
+
+  constructor(options: ISonosSsdpProbeOptions = {}) {
+    this.scanDurationMs = duration(options.scanDurationMs ?? 3000, 20, 10000, 'scanDurationMs');
+    this.startupTimeoutMs = duration(options.startupTimeoutMs ?? 5000, 1, 60000, 'startupTimeoutMs');
+    this.dependencies = { ...options.dependencies };
+  }
+
+  public async probe(context: IDiscoveryContext): Promise<IDiscoveryProbeResult> {
+    context.abortSignal?.throwIfAborted();
+    const addresses = context.networkInterfaces?.filter((network) => network.family === 'IPv4' && !network.internal).map((network) => network.address);
+    if (addresses?.length === 0) return { candidates: [] };
+    const networkInterfaces = this.dependencies.networkInterfaces ?? plugins.os.networkInterfaces;
+    const discovery = new plugins.ecobridgeDeviceManager.SsdpDiscovery({
+      ...this.dependencies,
+      networkInterfaces: () => {
+        const interfaces = networkInterfaces();
+        if (addresses === undefined) return interfaces;
+        return Object.fromEntries(Object.entries(interfaces).map(([name, networks]) => [name,
+          networks?.filter((network) => addresses.includes(network.address) && network.family === 'IPv4' && !network.internal)]));
+      },
+    });
+    const failure = new AbortController();
+    const signal = AbortSignal.any([failure.signal, ...(context.abortSignal ? [context.abortSignal] : [])]);
+    const onError = (error: unknown): void => failure.abort(error);
+    discovery.on('error', onError);
+    let operationError: unknown;
+    let operationFailed = false;
+    try {
+      await discovery.start(['urn:schemas-upnp-org:device:ZonePlayer:1'], { signal, timeoutMs: this.startupTimeoutMs });
+      await observe(this.scanDurationMs, signal);
+      if (discovery.lastError !== null) throw discovery.lastError;
+      const matcher = new SonosSsdpMatcher();
+      const candidates = new Map<string, IDiscoveryCandidate>();
+      for (const device of discovery.getDevices()) {
+        const match = await matcher.matches({ st: device.serviceType, usn: device.usn, location: device.location });
+        if (match.matched && match.candidate?.id) candidates.set(match.candidate.id, match.candidate);
+      }
+      signal.throwIfAborted();
+      return { candidates: [...candidates.values()] };
+    } catch (error) {
+      operationFailed = true;
+      operationError = error;
+      throw error;
+    } finally {
+      try { await discovery.stop(); }
+      catch (error) {
+        if (operationFailed) throw new AggregateError([operationError, error], 'Sonos discovery and cleanup failed.');
+        throw error;
+      } finally { discovery.off('error', onError); }
+    }
+  }
+}
+
+function duration(value: number, minimum: number, maximum: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) throw new Error(`Sonos ${name} must be an integer from ${minimum} to ${maximum}.`);
+  return value;
+}
+
+function observe(milliseconds: number, signal: AbortSignal): Promise<void> {
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const cleanup = (): void => { clearTimeout(timer); signal.removeEventListener('abort', onAbort); };
+    const onAbort = (): void => { cleanup(); reject(signal.reason); };
+    const timer = setTimeout(() => { cleanup(); resolve(); }, milliseconds);
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted) onAbort();
+  });
+}

package/ts/integrations/sonos/sonos.config.ts

@@ -0,0 +1,57 @@
+import type { ISonosConfig } from './sonos.types.js';
+
+export interface INormalizedSonosConfig extends ISonosConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly expectedUid?: string;
+  readonly timeoutMs: number;
+  readonly maxResponseBytes: number;
+  readonly pollIntervalMs: number;
+}
+
+export function normalizeSonosUid(value: unknown): string {
+  if (typeof value !== 'string' || !/^RINCON_[0-9a-f]{12}0?1400$/i.test(value)) {
+    throw new Error('Sonos player identity must be a RINCON UUID.');
+  }
+  return value.toUpperCase();
+}
+
+export function isSonosDataRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return false;
+  return Reflect.ownKeys(value).every((key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return typeof key === 'string' && descriptor !== undefined && 'value' in descriptor;
+  });
+}
+
+export function normalizeSonosConfig(input: ISonosConfig): INormalizedSonosConfig {
+  if (!isSonosDataRecord(input) || !Object.hasOwn(input, 'host')) throw new Error('Sonos configuration must be a plain object containing its own host field.');
+  const allowed = new Set(['host', 'port', 'expectedUid', 'timeoutMs', 'maxResponseBytes', 'pollIntervalMs']);
+  for (const key of Reflect.ownKeys(input)) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (typeof key !== 'string' || !allowed.has(key) || !descriptor || !('value' in descriptor)) {
+      throw new Error('Sonos configuration contains an unsupported field.');
+    }
+  }
+  if (typeof input.host !== 'string' || input.host.length > 253 || !/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/i.test(input.host)
+    || input.host.split('.').some((label) => !label || label.length > 63 || label.startsWith('-') || label.endsWith('-'))) {
+    throw new Error('Sonos host must be a bare IPv4 address or DNS hostname.');
+  }
+  let hostname: string;
+  try { hostname = new URL(`http://${input.host}`).hostname; }
+  catch { throw new Error('Sonos host must be a valid IPv4 address or DNS hostname.'); }
+  if (hostname !== input.host.toLowerCase()) throw new Error('Sonos host must use its canonical IPv4 address or DNS hostname.');
+  const port = boundedInteger(input.port ?? 1400, 1, 65535, 'port');
+  const timeoutMs = boundedInteger(input.timeoutMs ?? 10000, 1, 120000, 'timeoutMs');
+  const maxResponseBytes = boundedInteger(input.maxResponseBytes ?? 1024 * 1024, 1024, 4 * 1024 * 1024, 'maxResponseBytes');
+  const pollIntervalMs = boundedInteger(input.pollIntervalMs ?? 5000, 100, 60000, 'pollIntervalMs');
+  return Object.freeze({
+    host: input.host.toLowerCase(), port, timeoutMs, maxResponseBytes, pollIntervalMs,
+    ...(input.expectedUid === undefined ? {} : { expectedUid: normalizeSonosUid(input.expectedUid) }),
+  });
+}
+
+function boundedInteger(value: number, minimum: number, maximum: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) throw new Error(`Sonos ${name} must be an integer from ${minimum} to ${maximum}.`);
+  return value;
+}

package/ts/integrations/sonos/sonos.discovery.ts

@@ -1,126 +1,8 @@
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
-import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
-import type { ISonosManualEntry, ISonosMdnsRecord, ISonosSsdpRecord } from './sonos.types.js';
+import { SonosCandidateValidator, SonosManualMatcher, SonosMdnsMatcher, SonosSsdpMatcher } from './sonos.matchers.js';
+import { SonosSsdpProbe } from './sonos.classes.ssdpprobe.js';
 
-const sonosUpnpSt = 'urn:schemas-upnp-org:device:ZonePlayer:1';
+export * from './sonos.matchers.js';
 
-export class SonosSsdpMatcher implements IDiscoveryMatcher<ISonosSsdpRecord> {
-  public id = 'sonos-ssdp-match';
-  public source = 'ssdp' as const;
-  public description = 'Recognize Sonos ZonePlayer SSDP advertisements.';
-
-  public async matches(recordArg: ISonosSsdpRecord): Promise<IDiscoveryMatch> {
-    const st = recordArg.st || recordArg.headers?.st || recordArg.headers?.ST;
-    const usn = recordArg.usn || recordArg.headers?.usn || recordArg.headers?.USN;
-    const location = recordArg.location || recordArg.headers?.location || recordArg.headers?.LOCATION;
-    const matched = st === sonosUpnpSt || Boolean(usn?.includes('RINCON_'));
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'SSDP record is not a Sonos ZonePlayer.' };
-    }
-    const url = location ? new URL(location) : undefined;
-    const id = usn?.match(/RINCON_[^:\s]+/)?.[0];
-    return {
-      matched: true,
-      confidence: id ? 'certain' : 'high',
-      reason: 'SSDP record matches Sonos ZonePlayer metadata.',
-      normalizedDeviceId: id,
-      candidate: {
-        source: 'ssdp',
-        integrationDomain: 'sonos',
-        id,
-        host: url?.hostname,
-        port: url?.port ? Number(url.port) : 1400,
-        manufacturer: 'Sonos',
-        model: 'ZonePlayer',
-        metadata: { st, usn, location },
-      },
-    };
-  }
-}
-
-export class SonosMdnsMatcher implements IDiscoveryMatcher<ISonosMdnsRecord> {
-  public id = 'sonos-mdns-match';
-  public source = 'mdns' as const;
-  public description = 'Recognize Sonos mDNS advertisements.';
-
-  public async matches(recordArg: ISonosMdnsRecord): Promise<IDiscoveryMatch> {
-    const type = recordArg.type?.toLowerCase() || '';
-    const name = recordArg.name?.toLowerCase() || '';
-    const matched = type === '_sonos._tcp.local.' || name.startsWith('sonos');
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'mDNS record is not a Sonos advertisement.' };
-    }
-    const id = recordArg.txt?.id || recordArg.txt?.uid || recordArg.name;
-    return {
-      matched: true,
-      confidence: id ? 'certain' : 'high',
-      reason: 'mDNS record matches Sonos metadata.',
-      normalizedDeviceId: id,
-      candidate: {
-        source: 'mdns',
-        integrationDomain: 'sonos',
-        id,
-        host: recordArg.host,
-        port: recordArg.port || 1400,
-        manufacturer: 'Sonos',
-        metadata: { mdnsName: recordArg.name, mdnsType: recordArg.type, txt: recordArg.txt },
-      },
-    };
-  }
-}
-
-export class SonosManualMatcher implements IDiscoveryMatcher<ISonosManualEntry> {
-  public id = 'sonos-manual-match';
-  public source = 'manual' as const;
-  public description = 'Recognize manual Sonos setup entries.';
-
-  public async matches(inputArg: ISonosManualEntry): Promise<IDiscoveryMatch> {
-    const matched = Boolean(inputArg.host || inputArg.model?.toLowerCase().includes('sonos') || inputArg.metadata?.sonos);
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'Manual entry does not contain Sonos setup hints.' };
-    }
-    return {
-      matched: true,
-      confidence: inputArg.host ? 'high' : 'medium',
-      reason: 'Manual entry can start Sonos setup.',
-      normalizedDeviceId: inputArg.id,
-      candidate: {
-        source: 'manual',
-        integrationDomain: 'sonos',
-        id: inputArg.id,
-        host: inputArg.host,
-        port: inputArg.port || 1400,
-        name: inputArg.name,
-        manufacturer: 'Sonos',
-        model: inputArg.model,
-        metadata: inputArg.metadata,
-      },
-    };
-  }
-}
-
-export class SonosCandidateValidator implements IDiscoveryValidator {
-  public id = 'sonos-candidate-validator';
-  public description = 'Validate Sonos candidate metadata.';
-
-  public async validate(candidateArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
-    const manufacturer = candidateArg.manufacturer?.toLowerCase() || '';
-    const model = candidateArg.model?.toLowerCase() || '';
-    const matched = candidateArg.integrationDomain === 'sonos' || manufacturer === 'sonos' || model.includes('zoneplayer') || model.includes('sonos');
-    return {
-      matched,
-      confidence: matched && candidateArg.host ? 'high' : matched ? 'medium' : 'low',
-      reason: matched ? 'Candidate has Sonos metadata.' : 'Candidate is not Sonos.',
-      candidate: matched ? candidateArg : undefined,
-      normalizedDeviceId: candidateArg.id,
-    };
-  }
-}
-
-export const createSonosDiscoveryDescriptor = (): DiscoveryDescriptor => {
-  return new DiscoveryDescriptor({ integrationDomain: 'sonos', displayName: 'Sonos' })
-    .addMatcher(new SonosSsdpMatcher())
-    .addMatcher(new SonosMdnsMatcher())
-    .addMatcher(new SonosManualMatcher())
-    .addValidator(new SonosCandidateValidator());
-};
+export const createSonosDiscoveryDescriptor = (): DiscoveryDescriptor => new DiscoveryDescriptor({ integrationDomain: 'sonos', displayName: 'Sonos' })
+  .addProbe(new SonosSsdpProbe()).addMatcher(new SonosSsdpMatcher()).addMatcher(new SonosMdnsMatcher()).addMatcher(new SonosManualMatcher()).addValidator(new SonosCandidateValidator());