@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/sonos/readme.md

@@ -0,0 +1,74 @@
+# Sonos
+
+The native local runtime uses the public UPnP client and transport/volume controllers
+from `@ecobridge.xyz/devicemanager`. It reads the configured renderer's device
+description, transport, position, volume, mute and ZoneGroupTopology over bounded
+HTTP/SOAP. No Home Assistant instance or Sonos cloud account is required.
+
+```typescript
+const runtime = await new SonosIntegration().setup({
+  host: '192.168.1.55',
+  expectedUid: 'RINCON_000E58ABCDEF01400',
+  pollIntervalMs: 5000,
+}, { abortSignal });
+
+const [device] = await runtime.devices();
+await runtime.writeFeature!({
+  device,
+  feature: device.features.find((feature) => feature.id === 'volume')!,
+  value: 35,
+});
+await runtime.destroy();
+```
+
+Configuration requires a bare IPv4 address or DNS hostname. The default port is
+1400. Optional identity pinning rejects a different renderer. Request deadlines
+default to 10 seconds and response bodies to 1 MiB. Production snapshot fixtures,
+credentials in URLs and arbitrary configuration fields are rejected.
+
+The discovery descriptor owns an active native SSDP probe. Its observation window
+defaults to three seconds, with a separate five-second startup budget. Caller
+cancellation reaches the owning SSDP lifecycle and drains sockets and description
+requests. `IDiscoveryContext.networkInterfaces` limits discovery to the selected
+actual interfaces; an explicitly empty scope performs no network I/O. Passive
+SSDP and explicit Sonos mDNS/manual candidates use the same strict admission rules.
+Discovered endpoints are verified during setup before becoming available devices.
+
+Devices and entities use renderer UUIDs, so room renames preserve identity. Group
+metadata comes from the renderer's reported topology; advertised member URLs are
+never followed. Playback controls require the selected renderer to be its group
+coordinator. A grouped member exposes its actual state and supports its own volume
+and mute controls without silently redirecting playback to another renderer.
+Bonded satellites require selecting their parent renderer.
+
+Feature writes support integer volume from 0 to 100, boolean mute and playback
+values `playing`, `paused` or `stopped`. Media-player services support `play`,
+`pause`, `stop`, `next_track`, `previous_track`, `volume_set`, `volume_mute` and
+`play_media`. Each service requires an exact selected device or entity target and
+its documented arguments. `volume_level` is a fraction from 0 to 1; `volume` is an
+integer percent. A successful SOAP acknowledgement is followed by a fresh read;
+state is never optimistically changed and failed or uncertain calls are not retried.
+`play_media` accepts `uri` or `media_content_id`. Supplying `title` also requires
+an explicit `mime_type`, such as `audio/mpeg` or `audio/flac`, for its audio DIDL
+metadata. The runtime does not guess the media format from an arbitrary URI.
+Stream URLs require an explicit hostname and `//` authority, using `http:`,
+`https:`, `x-sonos-http:` or `x-rincon-mp3radio:` without embedded credentials.
+Direct client calls use `playUri(uri, { title, mimeType }, abortSignal)`.
+
+Subscriptions are explicitly `local_poll`, with a default five-second interval.
+Each subscription owns one sequential poll, cancellation and cleanup. Failures
+emit unavailable/error events rather than manufacturing known state; subsequent
+scheduled reads can report recovery. Unsubscribe and destroy abort and drain
+pending work. There is no GENA push capability, grouping mutation, queue management,
+favorites, alarms or EQ in this runtime.
+
+Protocol references:
+
+- [devicemanager UPnP contracts](https://code.foss.global/ecobridge.xyz/devicemanager)
+- [SoCo's native Sonos service implementation](https://github.com/SoCo/SoCo/blob/master/soco/services.py)
+- [SoCo's ZoneGroupState XML contract](https://github.com/SoCo/SoCo/blob/master/soco/zonegroupstate.py)
+
+The local UPnP wire contract was checked against those primary implementation
+sources. Sonos's current public developer portal documents its cloud Control API;
+it does not provide an openly accessible complete local UPnP specification.
+Verification uses local real HTTP/SOAP fixtures; owner hardware was not accessed.

package/ts/integrations/sonos/sonos.classes.client.ts

@@ -1,241 +1,169 @@
-import type { ISonosConfig, ISonosPositionInfo, ISonosSnapshot, ISonosSpeakerInfo, ISonosTransportInfo } from './sonos.types.js';
+import * as plugins from '../../plugins.js';
+import { isSonosDataRecord, normalizeSonosConfig, normalizeSonosUid, type INormalizedSonosConfig } from './sonos.config.js';
+import { parseSonosGroup } from './sonos.topology.js';
+import type { ISonosConfig, ISonosGroup, ISonosMediaOptions, ISonosPositionInfo, ISonosSnapshot, ISonosSpeakerInfo, ISonosTransportInfo } from './sonos.types.js';
+import { readSonosXmlElement, readSonosText, readSonosOptionalText } from './sonos.xml.js';
 
-type TSonosServiceType = 'AVTransport' | 'RenderingControl' | 'DeviceProperties';
+const transportPath = '/MediaRenderer/AVTransport/Control';
 
 export class SonosClient {
-  constructor(private readonly config: ISonosConfig) {}
-
-  public async getSnapshot(): Promise<ISonosSnapshot> {
-    const speakerInfo = await this.getSpeakerInfo();
-    const [transportInfo, positionInfo, volume, muted] = await Promise.all([
-      this.getTransportInfo(),
-      this.getPositionInfo(),
-      this.getVolume(),
-      this.getMute(),
-    ]);
-    return { speakerInfo, transportInfo, positionInfo, volume, muted };
-  }
-
-  public async getSpeakerInfo(): Promise<ISonosSpeakerInfo> {
-    if (this.config.speakerInfo) {
-      return this.config.speakerInfo;
-    }
-    const xml = await this.fetchText('/xml/device_description.xml');
-    const uid = this.stripUuid(this.readXmlTag(xml, 'UDN') || this.config.host || 'unknown');
-    const zoneName = this.readXmlTag(xml, 'roomName') || this.readXmlTag(xml, 'friendlyName') || `Sonos ${uid}`;
-    return {
-      uid,
-      zoneName,
-      modelName: this.readXmlTag(xml, 'modelName'),
-      modelNumber: this.readXmlTag(xml, 'modelNumber'),
-      serialNumber: this.readXmlTag(xml, 'serialNum'),
-      softwareVersion: this.readXmlTag(xml, 'softwareVersion'),
-      manufacturer: this.readXmlTag(xml, 'manufacturer') || 'Sonos',
-    };
-  }
-
-  public async getTransportInfo(): Promise<ISonosTransportInfo> {
-    if (this.config.transportInfo) {
-      return this.config.transportInfo;
-    }
-    const result = await this.soap('AVTransport', 'GetTransportInfo', [
-      ['InstanceID', 0],
-    ]);
-    return {
-      currentTransportState: result.CurrentTransportState,
-      currentTransportStatus: result.CurrentTransportStatus,
-      currentSpeed: result.CurrentSpeed,
-    };
-  }
-
-  public async getPositionInfo(): Promise<ISonosPositionInfo> {
-    if (this.config.positionInfo) {
-      return this.config.positionInfo;
-    }
-    const result = await this.soap('AVTransport', 'GetPositionInfo', [
-      ['InstanceID', 0],
-    ]);
-    const metadata = result.TrackMetaData || '';
-    return {
-      track: Number(result.Track || 0),
-      trackDuration: result.TrackDuration,
-      trackMetaData: metadata,
-      trackUri: result.TrackURI,
-      relativeTime: result.RelTime,
-      title: this.readXmlTag(metadata, 'dc:title') || this.readXmlTag(metadata, 'title'),
-      artist: this.readXmlTag(metadata, 'dc:creator') || this.readXmlTag(metadata, 'creator'),
-      album: this.readXmlTag(metadata, 'upnp:album') || this.readXmlTag(metadata, 'album'),
-      albumArtUri: this.readXmlTag(metadata, 'upnp:albumArtURI') || this.readXmlTag(metadata, 'albumArtURI'),
-    };
-  }
-
-  public async getVolume(): Promise<number | undefined> {
-    if (typeof this.config.volume === 'number') {
-      return this.config.volume;
-    }
-    const result = await this.soap('RenderingControl', 'GetVolume', [
-      ['InstanceID', 0],
-      ['Channel', 'Master'],
-    ]);
-    return Number(result.CurrentVolume);
-  }
-
-  public async getMute(): Promise<boolean | undefined> {
-    if (typeof this.config.muted === 'boolean') {
-      return this.config.muted;
-    }
-    const result = await this.soap('RenderingControl', 'GetMute', [
-      ['InstanceID', 0],
-      ['Channel', 'Master'],
-    ]);
-    return result.CurrentMute === '1' || result.CurrentMute?.toLowerCase() === 'true';
-  }
-
-  public async play(): Promise<void> {
-    await this.soap('AVTransport', 'Play', [
-      ['InstanceID', 0],
-      ['Speed', 1],
-    ]);
-  }
-
-  public async pause(): Promise<void> {
-    await this.soap('AVTransport', 'Pause', [
-      ['InstanceID', 0],
-      ['Speed', 1],
-    ]);
-  }
-
-  public async stop(): Promise<void> {
-    await this.soap('AVTransport', 'Stop', [
-      ['InstanceID', 0],
-      ['Speed', 1],
-    ]);
-  }
-
-  public async next(): Promise<void> {
-    await this.soap('AVTransport', 'Next', [
-      ['InstanceID', 0],
-      ['Speed', 1],
-    ]);
-  }
-
-  public async previous(): Promise<void> {
-    await this.soap('AVTransport', 'Previous', [
-      ['InstanceID', 0],
-      ['Speed', 1],
-    ]);
-  }
-
-  public async setVolume(volumeArg: number): Promise<void> {
-    const volume = Math.max(0, Math.min(100, Math.round(volumeArg)));
-    await this.soap('RenderingControl', 'SetVolume', [
-      ['InstanceID', 0],
-      ['Channel', 'Master'],
-      ['DesiredVolume', volume],
-    ]);
-  }
-
-  public async setMute(mutedArg: boolean): Promise<void> {
-    await this.soap('RenderingControl', 'SetMute', [
-      ['InstanceID', 0],
-      ['Channel', 'Master'],
-      ['DesiredMute', mutedArg ? 1 : 0],
-    ]);
-  }
-
-  public async playUri(uriArg: string, titleArg?: string): Promise<void> {
-    await this.soap('AVTransport', 'SetAVTransportURI', [
-      ['InstanceID', 0],
-      ['CurrentURI', uriArg],
-      ['CurrentURIMetaData', titleArg ? this.createMinimalRadioMetadata(titleArg) : ''],
-    ]);
-    await this.play();
-  }
-
-  public async destroy(): Promise<void> {}
-
-  private async soap(serviceTypeArg: TSonosServiceType, actionArg: string, argsArg: Array<[string, string | number | boolean]>): Promise<Record<string, string>> {
-    const path = this.servicePath(serviceTypeArg);
-    const body = this.createSoapEnvelope(serviceTypeArg, actionArg, argsArg);
-    const response = await globalThis.fetch(`${this.baseUrl()}${path}`, {
-      method: 'POST',
-      headers: {
-        'content-type': 'text/xml; charset="utf-8"',
-        soapaction: `urn:schemas-upnp-org:service:${serviceTypeArg}:1#${actionArg}`,
-      },
-      body,
+  public readonly config: INormalizedSonosConfig;
+  private readonly lifetime = new AbortController();
+  private readonly soap: plugins.ecobridgeDeviceManager.UpnpSoapClient;
+  private readonly playback: plugins.ecobridgeDeviceManager.UpnpPlaybackController;
+  private readonly volume: plugins.ecobridgeDeviceManager.UpnpVolumeController;
+  private readonly operations = new Set<Promise<unknown>>();
+  private selectedUid?: string;
+  private closePromise?: Promise<void>;
+
+  constructor(config: ISonosConfig, private readonly abortSignal?: AbortSignal) {
+    this.config = normalizeSonosConfig(config);
+    const baseUrl = `http://${this.config.host}:${this.config.port}`;
+    this.soap = new plugins.ecobridgeDeviceManager.UpnpSoapClient(baseUrl, {
+      timeoutMs: this.config.timeoutMs, maxResponseBytes: this.config.maxResponseBytes,
+      abortSignal: this.signal(),
     });
-    const text = await response.text();
-    if (!response.ok) {
-      throw new Error(`Sonos SOAP ${serviceTypeArg}.${actionArg} failed with HTTP ${response.status}: ${text}`);
-    }
-    return this.unwrapSoapResponse(text);
-  }
-
-  private async fetchText(pathArg: string): Promise<string> {
-    if (!this.config.host) {
-      throw new Error('Sonos host is required when fixture data is not provided.');
-    }
-    const response = await globalThis.fetch(`${this.baseUrl()}${pathArg}`);
-    if (!response.ok) {
-      throw new Error(`Sonos request ${pathArg} failed with HTTP ${response.status}: ${await response.text()}`);
-    }
-    return response.text();
-  }
-
-  private createSoapEnvelope(serviceTypeArg: TSonosServiceType, actionArg: string, argsArg: Array<[string, string | number | boolean]>): string {
-    const args = argsArg.map(([nameArg, valueArg]) => `<${nameArg}>${this.escapeXml(String(valueArg))}</${nameArg}>`).join('');
-    return `<?xml version="1.0"?><s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><s:Body><u:${actionArg} xmlns:u="urn:schemas-upnp-org:service:${serviceTypeArg}:1">${args}</u:${actionArg}></s:Body></s:Envelope>`;
-  }
-
-  private createMinimalRadioMetadata(titleArg: string): string {
-    return `<DIDL-Lite xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/" xmlns:r="urn:schemas-rinconnetworks-com:metadata-1-0/" xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/"><item id="R:0/0/0" parentID="R:0/0" restricted="true"><dc:title>${this.escapeXml(titleArg)}</dc:title><upnp:class>object.item.audioItem.audioBroadcast</upnp:class><desc id="cdudn" nameSpace="urn:schemas-rinconnetworks-com:metadata-1-0/">SA_RINCON65031_</desc></item></DIDL-Lite>`;
-  }
-
-  private unwrapSoapResponse(xmlArg: string): Record<string, string> {
-    const response: Record<string, string> = {};
-    const regex = /<([A-Za-z0-9_:]+)>([^<>]*)<\/\1>/g;
-    let match: RegExpExecArray | null;
-    while ((match = regex.exec(xmlArg))) {
-      response[this.localName(match[1])] = this.unescapeXml(match[2]);
+    this.playback = plugins.ecobridgeDeviceManager.UpnpPlaybackController.forSonos(this.config.host, this.config.port, this.soap);
+    this.volume = plugins.ecobridgeDeviceManager.UpnpVolumeController.forSonos(this.config.host, this.config.port, this.soap);
+  }
+
+  public getSnapshot(abortSignal?: AbortSignal): Promise<ISonosSnapshot> {
+    return this.request(async (signal) => {
+      const speakerInfo = await this.getSpeakerInfo(signal);
+      const [group, transportInfo, positionInfo, volume, muted] = await settledValues([
+        this.getGroup(speakerInfo.uid, signal), this.getTransportInfo(signal), this.getPositionInfo(signal),
+        this.volume.getVolume(signal), this.volume.getMute(signal),
+      ] as const);
+      return { speakerInfo, group, transportInfo, positionInfo, volume, muted, observedAt: new Date().toISOString() };
+    }, abortSignal);
+  }
+
+  public getSpeakerInfo(abortSignal?: AbortSignal): Promise<ISonosSpeakerInfo> {
+    return this.request(async (signal) => {
+      const xml = await this.soap.getXml('/xml/device_description.xml', signal);
+      const root = readSonosXmlElement(this.soap.parseXml(xml).root, 'device description');
+      if (root['@_xmlns'] !== 'urn:schemas-upnp-org:device-1-0') throw new Error('Sonos device description has an invalid namespace.');
+      const device = readSonosXmlElement(root.device, 'renderer');
+      if (readSonosText(device, 'deviceType') !== 'urn:schemas-upnp-org:device:ZonePlayer:1' || !['sonos', 'sonos, inc.'].includes(readSonosText(device, 'manufacturer').toLowerCase())) {
+        throw new Error('Configured endpoint is not a Sonos ZonePlayer.');
+      }
+      const uid = normalizeSonosUid(readSonosText(device, 'UDN').replace(/^uuid:/i, ''));
+      const expectedUid = this.config.expectedUid ?? this.selectedUid;
+      if (expectedUid && uid !== expectedUid) throw new Error('Sonos renderer identity changed or does not match configuration.');
+      this.selectedUid ??= uid;
+      const zoneXml = await this.soap.soapAction('/DeviceProperties/Control', 'urn:schemas-upnp-org:service:DeviceProperties:1', 'GetZoneAttributes', {}, signal);
+      const zoneName = this.soap.extractValue(zoneXml, 'CurrentZoneName');
+      if (!zoneName.trim() || zoneName.length > 256) throw new Error('Sonos zone name is invalid.');
+      return {
+        uid, zoneName, manufacturer: 'Sonos', modelName: readSonosOptionalText(device, 'modelName'),
+        modelNumber: readSonosOptionalText(device, 'modelNumber'), serialNumber: readSonosOptionalText(device, 'serialNum'),
+        softwareVersion: readSonosOptionalText(device, 'softwareVersion'),
+      };
+    }, abortSignal);
+  }
+
+  public getTransportInfo(abortSignal?: AbortSignal): Promise<ISonosTransportInfo> {
+    return this.request(async (signal) => {
+      const transport = await this.soap.getTransportInfo(transportPath, signal);
+      return { currentTransportState: transport.state, currentTransportStatus: transport.status, currentSpeed: transport.speed };
+    }, abortSignal);
+  }
+
+  public getPositionInfo(abortSignal?: AbortSignal): Promise<ISonosPositionInfo> {
+    return this.request(async (signal) => {
+      const position = await this.soap.getPositionInfo(transportPath, signal);
+      const metadata = position.trackMetadata && position.trackMetadata !== 'NOT_IMPLEMENTED'
+        ? this.soap.extractOptionalValues(position.trackMetadata, ['title', 'creator', 'artist', 'album', 'albumArtURI']) : {};
+      return {
+        track: position.track, trackDuration: position.trackDuration, trackMetaData: position.trackMetadata,
+        trackUri: position.trackUri, relativeTime: position.relativeTime, title: metadata.title,
+        artist: metadata.creator ?? metadata.artist, album: metadata.album, albumArtUri: metadata.albumArtURI,
+      };
+    }, abortSignal);
+  }
+
+  public getVolume(signal?: AbortSignal): Promise<number> { return this.request((signal) => this.volume.getVolume(signal), signal); }
+  public getMute(signal?: AbortSignal): Promise<boolean> { return this.request((signal) => this.volume.getMute(signal), signal); }
+  public play(signal?: AbortSignal): Promise<void> { return this.transport((signal) => this.playback.play(undefined, signal), signal); }
+  public pause(signal?: AbortSignal): Promise<void> { return this.transport((signal) => this.playback.pause(signal), signal); }
+  public stop(signal?: AbortSignal): Promise<void> { return this.transport((signal) => this.playback.stop(signal), signal); }
+  public next(signal?: AbortSignal): Promise<void> { return this.transport((signal) => this.playback.next(signal), signal); }
+  public previous(signal?: AbortSignal): Promise<void> { return this.transport((signal) => this.playback.previous(signal), signal); }
+
+  public setVolume(value: number, signal?: AbortSignal): Promise<void> {
+    if (!Number.isInteger(value) || value < 0 || value > 100) throw new Error('Sonos volume must be an integer from 0 to 100.');
+    return this.request(async (signal) => { await this.getSpeakerInfo(signal); await this.volume.setVolume(value, signal); }, signal);
+  }
+
+  public setMute(value: boolean, signal?: AbortSignal): Promise<void> {
+    if (typeof value !== 'boolean') throw new Error('Sonos mute must be boolean.');
+    return this.request(async (signal) => { await this.getSpeakerInfo(signal); await this.volume.setMute(value, signal); }, signal);
+  }
+
+  public playUri(uri: string, options: ISonosMediaOptions = {}, signal?: AbortSignal): Promise<void> {
+    if (!isSonosDataRecord(options) || Object.keys(options).some((key) => !['title', 'mimeType'].includes(key))) throw new Error('Sonos media options contain unsupported fields.');
+    const { title, mimeType } = options;
+    if (typeof uri !== 'string' || uri.length > 4096 || /[\x00-\x20]/.test(uri)) throw new Error('Sonos media URI is invalid.');
+    const url = new URL(uri);
+    if (!['http:', 'https:', 'x-sonos-http:', 'x-rincon-mp3radio:'].includes(url.protocol) || !url.hostname
+      || uri.slice(url.protocol.length, url.protocol.length + 2) !== '//' || url.username || url.password) throw new Error('Sonos media URI must use an uncredentialed supported stream URL.');
+    if (title !== undefined && (typeof title !== 'string' || !title.trim() || title.length > 256)) throw new Error('Sonos media title is invalid.');
+    if (mimeType !== undefined && (typeof mimeType !== 'string' || !/^audio\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/i.test(mimeType))) throw new Error('Sonos MIME type must identify a specific audio format.');
+    if (title !== undefined && mimeType === undefined) throw new Error('Sonos titled media requires an explicit audio MIME type.');
+    const metadata = title === undefined ? '' : this.soap.generateDidlMetadata(title, uri, mimeType);
+    return this.transport(async (signal) => {
+      await this.soap.setAVTransportURI(transportPath, uri, metadata, signal);
+      await this.playback.play(undefined, signal);
+    }, signal);
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.lifetime.abort(new Error('Sonos client is closed.'));
+      this.closePromise = (async () => {
+        const results = await Promise.allSettled([this.playback.close(), this.volume.close(), this.soap.close()]);
+        await Promise.allSettled([...this.operations]);
+        const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+        if (failures.length) throw new AggregateError(failures.map((result) => result.reason), 'Sonos client cleanup failed.');
+      })();
     }
-    return response;
+    return this.closePromise;
   }
 
-  private readXmlTag(xmlArg: string, tagArg: string): string | undefined {
-    const escapedTag = tagArg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const regex = new RegExp(`<(?:[A-Za-z0-9_]+:)?${escapedTag}>([\\s\\S]*?)<\\/(?:[A-Za-z0-9_]+:)?${escapedTag}>`, 'i');
-    const match = regex.exec(xmlArg);
-    return match?.[1] ? this.unescapeXml(match[1].trim()) : undefined;
+  private getGroup(uid: string, signal: AbortSignal): Promise<ISonosGroup> {
+    return this.request(async (signal) => {
+      const response = await this.soap.soapAction('/ZoneGroupTopology/Control', 'urn:schemas-upnp-org:service:ZoneGroupTopology:1', 'GetZoneGroupState', {}, signal);
+      return parseSonosGroup(this.soap.parseXml(this.soap.extractValue(response, 'ZoneGroupState')), uid);
+    }, signal);
   }
 
-  private servicePath(serviceTypeArg: TSonosServiceType): string {
-    if (serviceTypeArg === 'RenderingControl') {
-      return '/MediaRenderer/RenderingControl/Control';
-    }
-    if (serviceTypeArg === 'DeviceProperties') {
-      return '/DeviceProperties/Control';
-    }
-    return '/MediaRenderer/AVTransport/Control';
+  private transport(operation: (signal: AbortSignal) => Promise<void>, signal?: AbortSignal): Promise<void> {
+    return this.request(async (signal) => {
+      const speaker = await this.getSpeakerInfo(signal);
+      const group = await this.getGroup(speaker.uid, signal);
+      if (group.coordinatorUid !== speaker.uid) throw new Error('Sonos playback requires selecting the group coordinator.');
+      signal.throwIfAborted();
+      await operation(signal);
+    }, signal);
   }
 
-  private stripUuid(valueArg: string): string {
-    return valueArg.replace(/^uuid:/i, '');
+  private signal(signal?: AbortSignal): AbortSignal {
+    return AbortSignal.any([this.lifetime.signal, ...(this.abortSignal ? [this.abortSignal] : []), ...(signal ? [signal] : [])]);
   }
 
-  private localName(valueArg: string): string {
-    return valueArg.includes(':') ? valueArg.split(':').pop() || valueArg : valueArg;
-  }
-
-  private baseUrl(): string {
-    return `http://${this.config.host}:${this.config.port || 1400}`;
-  }
-
-  private escapeXml(valueArg: string): string {
-    return valueArg.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+  private request<TResult>(operation: (signal: AbortSignal) => Promise<TResult>, signal?: AbortSignal): Promise<TResult> {
+    const combined = this.signal(signal);
+    combined.throwIfAborted();
+    const result = operation(combined);
+    this.operations.add(result);
+    void result.then(() => this.operations.delete(result), () => this.operations.delete(result));
+    return result;
   }
+}
 
-  private unescapeXml(valueArg: string): string {
-    return valueArg.replace(/&apos;/g, "'").replace(/&quot;/g, '"').replace(/&gt;/g, '>').replace(/&lt;/g, '<').replace(/&amp;/g, '&');
-  }
+async function settledValues<TValues extends readonly unknown[]>(values: { [TKey in keyof TValues]: Promise<TValues[TKey]> }): Promise<TValues> {
+  const results = await Promise.allSettled(values);
+  const failure = results.find((result): result is PromiseRejectedResult => result.status === 'rejected');
+  if (failure) throw failure.reason;
+  return results.map((result) => (result as PromiseFulfilledResult<unknown>).value) as unknown as TValues;
 }

package/ts/integrations/sonos/sonos.classes.configflow.ts

@@ -1,9 +1,12 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
 import type { ISonosConfig } from './sonos.types.js';
+import { isSonosDataRecord, normalizeSonosConfig } from './sonos.config.js';
 
 export class SonosConfigFlow implements IConfigFlow<ISonosConfig> {
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<ISonosConfig>> {
     void contextArg;
+    if (!isSonosDataRecord(candidateArg) || candidateArg.integrationDomain !== 'sonos') return { kind: 'error', error: 'Candidate does not belong to Sonos.' };
+    candidateArg = { source: candidateArg.source, integrationDomain: 'sonos', host: candidateArg.host, port: candidateArg.port, id: candidateArg.id };
     return {
       kind: 'form',
       title: 'Connect Sonos',
@@ -12,14 +15,24 @@ export class SonosConfigFlow implements IConfigFlow<ISonosConfig> {
         { name: 'host', label: 'Host', type: 'text', required: true },
         { name: 'port', label: 'Port', type: 'number' },
       ],
-      submit: async (valuesArg) => ({
-        kind: 'done',
-        title: 'Sonos configured',
-        config: {
-          host: String(valuesArg.host || candidateArg.host || ''),
-          port: typeof valuesArg.port === 'number' ? valuesArg.port : candidateArg.port || 1400,
-        },
-      }),
+      submit: async (valuesArg) => {
+        if (!isSonosDataRecord(valuesArg)) throw new Error('Sonos form values must be a plain object.');
+        for (const key of Reflect.ownKeys(valuesArg)) {
+          const descriptor = Object.getOwnPropertyDescriptor(valuesArg, key);
+          if (typeof key !== 'string' || !['host', 'port'].includes(key) || !descriptor || !('value' in descriptor)) throw new Error('Sonos form contains an unsupported field.');
+        }
+        if (valuesArg.host !== undefined && typeof valuesArg.host !== 'string') throw new Error('Sonos host must be text.');
+        if (valuesArg.port !== undefined && typeof valuesArg.port !== 'number') throw new Error('Sonos port must be numeric.');
+        return {
+          kind: 'done',
+          title: 'Sonos configured',
+          config: normalizeSonosConfig({
+            host: typeof valuesArg.host === 'string' ? valuesArg.host : candidateArg.host ?? '',
+            port: typeof valuesArg.port === 'number' ? valuesArg.port : candidateArg.port ?? 1400,
+            ...(candidateArg.id ? { expectedUid: candidateArg.id } : {}),
+          }),
+        };
+      },
     };
   }
 }