@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/soundtouch/soundtouch.classes.configflow.ts

@@ -1,55 +1,60 @@
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
-import type { ISoundtouchConfig } from './soundtouch.types.js';
-import { soundtouchDefaultDlnaPort, soundtouchDefaultPort } from './soundtouch.types.js';
+import { SoundtouchClient } from './soundtouch.classes.client.js';
+import { createSoundtouchDiscoveryDescriptor } from './soundtouch.discovery.js';
+import type { ISoundtouchConfig, ISoundtouchHomeOptions } from './soundtouch.types.js';
+import { normalizeSoundtouchConfig, soundtouchKeys, soundtouchRecord, soundtouchText } from './soundtouch.validation.js';
 
 export class SoundtouchConfigFlow implements IConfigFlow<ISoundtouchConfig> {
+  readonly #owner: NativeIntegrationOwner;
+  readonly #scope: NativeIntegrationScope;
+  readonly #standalone: boolean;
+  public constructor(optionsArg: ISoundtouchHomeOptions | NativeIntegrationOwner = {}) {
+    this.#standalone = !(optionsArg instanceof NativeIntegrationOwner);
+    this.#owner = optionsArg instanceof NativeIntegrationOwner ? optionsArg : new NativeIntegrationOwner('soundtouch', optionsArg);
+    this.#scope = this.#owner.createFlowScope();
+  }
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<ISoundtouchConfig>> {
-    void contextArg;
+    // Capture host authority synchronously before the matcher or any submission can await.
+    const context = this.#scope.admit(contextArg);
+    const matched = await createSoundtouchDiscoveryDescriptor().getValidators()[0].validate(candidateArg, {});
+    if (!matched.matched || !matched.candidate) return { kind: 'error', error: matched.reason };
+    const candidate = matched.candidate;
     return {
-      kind: 'form',
-      title: 'Connect Bose SoundTouch',
-      description: candidateArg.source === 'manual'
-        ? 'Configure a local Bose SoundTouch speaker.'
-        : 'Confirm or adjust the discovered local Bose SoundTouch speaker.',
+      kind: 'form', title: 'Connect selected Bose SoundTouch speaker',
+      description: 'Acknowledge the plaintext LAN connection and choose an absolute integer volume ceiling. The host home and selected endpoint/deviceID/type stay fixed.',
       fields: [
-        { name: 'host', label: 'Host', type: 'text', required: true },
-        { name: 'port', label: 'Port', type: 'number' },
-        { name: 'name', label: 'Name', type: 'text' },
+        { name: 'allowUnencryptedLan', label: 'Acknowledge unauthenticated plaintext LAN', type: 'boolean', required: true },
+        { name: 'volumeLimit', label: 'Maximum absolute volume (0–100)', type: 'number', required: true },
+        { name: 'name', label: 'Local display label', type: 'text' },
       ],
       submit: async (valuesArg) => {
-        const host = stringValue(valuesArg.host) || candidateArg.host;
-        if (!host) {
-          return { kind: 'error', title: 'SoundTouch host required', error: 'SoundTouch setup requires a host.' };
+        try {
+          const values = soundtouchRecord(valuesArg, 'config flow values');
+          soundtouchKeys(values, ['homeId', 'allowUnencryptedLan', 'volumeLimit', 'name', 'requestTimeoutMs', 'maxPendingOperations', 'maxResponseBytes']);
+          if (values.homeId !== undefined && soundtouchText(values.homeId, 'submitted homeId', 256) !== context.homeId) {
+            throw new TypeError('SoundTouch submitted home conflicts with the captured host home.');
+          }
+          const config = normalizeSoundtouchConfig({ ...values, homeId: context.homeId,
+            host: candidate.host, port: candidate.port, deviceId: candidate.id, type: candidate.metadata?.type });
+          return await this.#scope.run(context, config.homeId, async (leaseArg) => {
+            const client = new SoundtouchClient(config, { ...leaseArg.context, abortSignal: leaseArg.signal });
+            let cleanupAttempted = false;
+            leaseArg.own(async () => {
+              if (cleanupAttempted) return client.retryCleanup();
+              cleanupAttempted = true;
+              await client.destroy();
+            });
+            await client.getSnapshot(leaseArg.signal);
+            leaseArg.assertOpen();
+            return { kind: 'done' as const, title: 'Selected SoundTouch speaker verified', config };
+          });
+        } catch (errorArg) {
+          return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'SoundTouch selected setup failed.' };
         }
-        return {
-          kind: 'done',
-          title: 'Bose SoundTouch configured',
-          config: {
-            host,
-            port: numberValue(valuesArg.port) || candidateArg.port || soundtouchDefaultPort,
-            dlnaPort: soundtouchDefaultDlnaPort,
-            name: stringValue(valuesArg.name) || candidateArg.name,
-            deviceId: candidateArg.id,
-            model: candidateArg.model,
-            macAddress: candidateArg.macAddress,
-          },
-        };
       },
     };
   }
+  public destroy(): Promise<void> { return this.#standalone ? this.#owner.close() : this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#standalone ? this.#owner.retryCleanup() : this.#scope.retryCleanup(); }
 }
-
-const stringValue = (valueArg: unknown): string | undefined => {
-  return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-};
-
-const numberValue = (valueArg: unknown): number | undefined => {
-  if (typeof valueArg === 'number' && Number.isFinite(valueArg)) {
-    return valueArg;
-  }
-  if (typeof valueArg === 'string' && valueArg.trim()) {
-    const parsed = Number(valueArg);
-    return Number.isFinite(parsed) ? parsed : undefined;
-  }
-  return undefined;
-};

package/ts/integrations/soundtouch/soundtouch.classes.integration.ts

@@ -1,178 +1,123 @@
-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 { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { SoundtouchClient } from './soundtouch.classes.client.js';
 import { SoundtouchConfigFlow } from './soundtouch.classes.configflow.js';
 import { createSoundtouchDiscoveryDescriptor } from './soundtouch.discovery.js';
 import { SoundtouchMapper } from './soundtouch.mapper.js';
-import type { ISoundtouchCommandRequest, ISoundtouchConfig, TSoundtouchCommand } from './soundtouch.types.js';
+import type { ISoundtouchConfig, ISoundtouchHomeOptions, ISoundtouchSnapshot } from './soundtouch.types.js';
+import { soundtouchProfile } from './soundtouch.types.js';
+import { normalizeSoundtouchConfig, soundtouchBoolean, soundtouchInteger, soundtouchKeys, soundtouchRecord } from './soundtouch.validation.js';
 
 export class SoundtouchIntegration extends BaseIntegration<ISoundtouchConfig> {
   public readonly domain = 'soundtouch';
   public readonly displayName = 'Bose SoundTouch';
   public readonly status = 'control-runtime' as const;
+  public readonly metadata = soundtouchProfile.metadata;
   public readonly discoveryDescriptor = createSoundtouchDiscoveryDescriptor();
-  public readonly configFlow = new SoundtouchConfigFlow();
-  public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/soundtouch',
-    upstreamDomain: 'soundtouch',
-    integrationType: 'device',
-    iotClass: 'local_polling',
-    requirements: ['libsoundtouch==0.8'],
-    dependencies: [],
-    afterDependencies: [],
-    codeowners: ['@kroimon'],
-    configFlow: true,
-    documentation: 'https://www.home-assistant.io/integrations/soundtouch',
-    zeroconf: ['_soundtouch._tcp.local.'],
-  };
+  public readonly configFlow: SoundtouchConfigFlow;
+  readonly #owner: NativeIntegrationOwner;
 
-  public async setup(configArg: ISoundtouchConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new SoundtouchRuntime(new SoundtouchClient(configArg));
+  public constructor(optionsArg: ISoundtouchHomeOptions = {}) {
+    super();
+    this.#owner = new NativeIntegrationOwner('soundtouch', optionsArg);
+    this.configFlow = new SoundtouchConfigFlow(this.#owner);
   }
-
-  public async destroy(): Promise<void> {}
+  public setup(configArg: ISoundtouchConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    const config = normalizeSoundtouchConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const client = new SoundtouchClient(config, { ...leaseArg.context, abortSignal: leaseArg.signal });
+      let cleanupAttempted = false;
+      leaseArg.own(async () => {
+        if (cleanupAttempted) return client.retryCleanup();
+        cleanupAttempted = true;
+        await client.destroy();
+      });
+      const snapshot = await client.getSnapshot(leaseArg.signal);
+      leaseArg.assertOpen();
+      const runtime = new SoundtouchRuntime(client, snapshot, leaseArg);
+      leaseArg.promoteToRuntime();
+      return runtime;
+    });
+  }
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
-
 export class HomeAssistantSoundtouchIntegration extends SoundtouchIntegration {}
 
 class SoundtouchRuntime implements IIntegrationRuntime {
-  public domain = 'soundtouch';
-
-  constructor(private readonly client: SoundtouchClient) {}
-
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return SoundtouchMapper.toDevices(await this.client.getSnapshot());
+  public readonly domain = 'soundtouch';
+  readonly #deviceId: string;
+  readonly #entityId: string;
+  constructor(private readonly client: SoundtouchClient, snapshotArg: ISoundtouchSnapshot, private readonly lease: INativeSetupLease) {
+    this.#deviceId = SoundtouchMapper.deviceId(snapshotArg);
+    this.#entityId = SoundtouchMapper.mediaEntityId(snapshotArg);
+  }
+  public isHealthy(): boolean { return !this.lease.signal.aborted && this.client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.lease.assertOpen(); return SoundtouchMapper.toDevices(await this.client.getSnapshot(signalArg));
   }
-
   public async entities(): Promise<IIntegrationEntity[]> {
-    return SoundtouchMapper.toEntities(await this.client.getSnapshot());
+    this.lease.assertOpen(); return SoundtouchMapper.toEntities(await this.client.getSnapshot());
+  }
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.lease.assertOpen();
+    if (typeof handlerArg !== 'function') throw new TypeError('SoundTouch runtime subscriber must be a function.');
+    const unsubscribe = this.client.subscribe((eventArg) => {
+      handlerArg({ type: eventArg.type === 'error' ? 'error' : 'state_changed', integrationDomain: 'soundtouch',
+        deviceId: this.#deviceId, entityId: this.#entityId, timestamp: Date.now(),
+        data: eventArg.type === 'snapshot' ? { snapshot: eventArg.snapshot, entity: SoundtouchMapper.toEntities(eventArg.snapshot)[0] }
+          : eventArg.type === 'control' ? { observation: eventArg.observation, effectOutcome: 'indeterminate' }
+            : { message: eventArg.error.message } });
+    }, signalArg);
+    return async () => unsubscribe();
   }
-
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
     try {
-      if (requestArg.domain === 'media_player') {
-        return await this.callMediaPlayerService(requestArg);
+      this.lease.assertOpen();
+      const request = soundtouchRecord(requestArg, 'service request');
+      soundtouchKeys(request, ['domain', 'service', 'target', 'data']);
+      if (typeof request.domain !== 'string' || typeof request.service !== 'string') throw new TypeError('SoundTouch service domain and name must be strings.');
+      const target = soundtouchRecord(request.target, 'service target'); soundtouchKeys(target, ['deviceId', 'entityId']);
+      if (target.deviceId === undefined && target.entityId === undefined
+        || target.deviceId !== undefined && target.deviceId !== this.#deviceId
+        || target.entityId !== undefined && target.entityId !== this.#entityId) throw new TypeError('SoundTouch services require an exact owned home/device or speaker entity target.');
+      const data = request.data === undefined ? {} : soundtouchRecord(request.data, 'service data');
+      if (request.domain === 'soundtouch' && ['status', 'snapshot', 'refresh'].includes(request.service)) {
+        soundtouchKeys(data, []); return { success: true, data: await this.client.getSnapshot() };
       }
-      if (requestArg.domain === 'soundtouch') {
-        return await this.callSoundtouchService(requestArg);
+      if (request.domain !== 'soundtouch' && request.domain !== 'media_player') throw new TypeError('SoundTouch service domain is unsupported.');
+      if (request.service === 'set_volume' || request.service === 'volume_set') {
+        soundtouchKeys(data, ['volume']); return observed(await this.client.setVolume(soundtouchInteger(data.volume, 0, 100, 'absolute volume')));
       }
-      return { success: false, error: `Unsupported SoundTouch service domain: ${requestArg.domain}` };
-    } catch (errorArg) {
-      return { success: false, error: errorArg instanceof Error ? errorArg.message : String(errorArg) };
-    }
-  }
-
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
-  }
-
-  private async callMediaPlayerService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const command = this.commandFromMediaService(requestArg.service);
-    if (!command) {
-      return { success: false, error: `Unsupported SoundTouch media_player service: ${requestArg.service}` };
-    }
-    const result = await this.client.execute(this.commandRequest(command, requestArg));
-    return { success: true, data: result };
-  }
-
-  private async callSoundtouchService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.service === 'play_preset' || requestArg.service === 'select_preset') {
-      const presetId = this.stringData(requestArg, 'preset_id') || this.stringData(requestArg, 'preset') || this.stringData(requestArg, 'presetId') || this.numberStringData(requestArg, 'preset');
-      const presetName = this.stringData(requestArg, 'preset_name') || this.stringData(requestArg, 'presetName') || this.stringData(requestArg, 'name');
-      const result = await this.client.execute({ command: 'play_preset', presetId, presetName });
-      return { success: true, data: result };
-    }
-    if (requestArg.service === 'play' || requestArg.service === 'pause' || requestArg.service === 'media_play' || requestArg.service === 'media_pause' || requestArg.service === 'volume_set' || requestArg.service === 'volume_mute' || requestArg.service === 'select_source' || requestArg.service === 'play_media') {
-      return this.callMediaPlayerService({ ...requestArg, domain: 'media_player' });
-    }
-    return { success: false, error: `Unsupported SoundTouch service: ${requestArg.service}` };
-  }
-
-  private commandFromMediaService(serviceArg: string): TSoundtouchCommand | undefined {
-    if (serviceArg === 'turn_on') {
-      return 'turn_on';
-    }
-    if (serviceArg === 'turn_off') {
-      return 'turn_off';
-    }
-    if (serviceArg === 'media_play' || serviceArg === 'play') {
-      return 'play';
-    }
-    if (serviceArg === 'media_pause' || serviceArg === 'pause') {
-      return 'pause';
-    }
-    if (serviceArg === 'media_play_pause' || serviceArg === 'play_pause') {
-      return 'play_pause';
-    }
-    if (serviceArg === 'media_previous_track' || serviceArg === 'previous_track') {
-      return 'previous_track';
-    }
-    if (serviceArg === 'media_next_track' || serviceArg === 'next_track') {
-      return 'next_track';
-    }
-    if (serviceArg === 'volume_up') {
-      return 'volume_up';
-    }
-    if (serviceArg === 'volume_down') {
-      return 'volume_down';
-    }
-    if (serviceArg === 'volume_set' || serviceArg === 'set_volume') {
-      return 'set_volume';
-    }
-    if (serviceArg === 'volume_mute' || serviceArg === 'mute') {
-      return 'mute';
-    }
-    if (serviceArg === 'select_source' || serviceArg === 'select_input') {
-      return 'select_source';
-    }
-    if (serviceArg === 'play_media') {
-      return 'play_media';
-    }
-    return undefined;
-  }
-
-  private commandRequest(commandArg: TSoundtouchCommand, requestArg: IServiceCallRequest): ISoundtouchCommandRequest {
-    const request: ISoundtouchCommandRequest = { command: commandArg };
-    if (commandArg === 'set_volume') {
-      request.volumeLevel = this.numberData(requestArg, 'volume_level') ?? this.numberData(requestArg, 'volumeLevel');
-      request.volume = this.numberData(requestArg, 'volume');
-    }
-    if (commandArg === 'mute') {
-      request.muted = this.boolData(requestArg, 'is_volume_muted') ?? this.boolData(requestArg, 'mute') ?? this.boolData(requestArg, 'muted');
-    }
-    if (commandArg === 'select_source') {
-      request.source = this.stringData(requestArg, 'source') || this.stringData(requestArg, 'input');
-    }
-    if (commandArg === 'play_media') {
-      request.mediaId = this.stringData(requestArg, 'media_content_id') || this.stringData(requestArg, 'mediaId') || this.stringData(requestArg, 'uri') || this.numberStringData(requestArg, 'media_content_id');
-      request.mediaType = this.stringData(requestArg, 'media_content_type') || this.stringData(requestArg, 'mediaType');
-      request.url = this.stringData(requestArg, 'url');
-      request.presetId = this.stringData(requestArg, 'preset_id') || this.stringData(requestArg, 'presetId') || this.numberStringData(requestArg, 'preset');
-      request.presetName = this.stringData(requestArg, 'preset_name') || this.stringData(requestArg, 'presetName');
-    }
-    return request;
-  }
-
-  private stringData(requestArg: IServiceCallRequest, keyArg: string): string | undefined {
-    const value = requestArg.data?.[keyArg];
-    return typeof value === 'string' && value ? value : undefined;
-  }
-
-  private numberData(requestArg: IServiceCallRequest, keyArg: string): number | undefined {
-    const value = requestArg.data?.[keyArg];
-    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+      if (request.service === 'set_mute' || request.service === 'volume_mute') {
+        soundtouchKeys(data, ['muted']); return observed(await this.client.setMuted(soundtouchBoolean(data.muted)));
+      }
+      throw new TypeError('SoundTouch supports status reads and explicit absolute volume/mute only.');
+    } catch (errorArg) { return failed(errorArg); }
   }
-
-  private numberStringData(requestArg: IServiceCallRequest, keyArg: string): string | undefined {
-    const value = this.numberData(requestArg, keyArg);
-    return typeof value === 'number' ? String(value) : undefined;
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      this.lease.assertOpen();
+      const request = soundtouchRecord(requestArg, 'feature write'); soundtouchKeys(request, ['device', 'feature', 'value']);
+      const device = soundtouchRecord(request.device, 'feature device');
+      const feature = soundtouchRecord(request.feature, 'feature');
+      if (device.id !== this.#deviceId || device.integrationDomain !== 'soundtouch') throw new TypeError('SoundTouch feature device is outside this home runtime.');
+      if ((feature.id !== 'volume' && feature.id !== 'mute') || feature.capability !== 'media') throw new TypeError('SoundTouch feature is not an admitted absolute media control.');
+      const value = feature.id === 'volume' ? soundtouchInteger(request.value, 0, 100, 'absolute volume') : soundtouchBoolean(request.value);
+      return observed(await this.client.writeFeature(feature.id, value, signalArg));
+    } catch (errorArg) { return failed(errorArg); }
   }
+  public destroy(): Promise<void> { return this.lease.close(); }
+}
 
-  private boolData(requestArg: IServiceCallRequest, keyArg: string): boolean | undefined {
-    const value = requestArg.data?.[keyArg];
-    return typeof value === 'boolean' ? value : undefined;
-  }
+function observed(observationArg: plugins.ecobridgeDeviceManager.IBoseSoundTouchControlResult): IServiceCallResult {
+  return { success: false, data: { ...observationArg, effectOutcome: 'indeterminate' } };
+}
+function failed(errorArg: unknown): IServiceCallResult {
+  return { success: false, error: errorArg instanceof Error ? errorArg.message : 'SoundTouch operation failed.', data: {
+    effectOutcome: errorArg instanceof plugins.ecobridgeDeviceManager.BoseSoundTouchProtocolError ? errorArg.effectOutcome : 'not-sent',
+    code: errorArg instanceof plugins.ecobridgeDeviceManager.BoseSoundTouchProtocolError ? errorArg.code : 'INVALID_OPERATION',
+  } };
 }

package/ts/integrations/soundtouch/soundtouch.discovery.ts

@@ -1,137 +1,25 @@
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
-import type { IDiscoveryCandidate, IDiscoveryContext, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
-import type { ISoundtouchManualEntry, ISoundtouchMdnsRecord } from './soundtouch.types.js';
-import { soundtouchDefaultPort } from './soundtouch.types.js';
-
-const soundtouchDomain = 'soundtouch';
-const soundtouchMdnsType = '_soundtouch._tcp.local.';
-
-export class SoundtouchMdnsMatcher implements IDiscoveryMatcher<ISoundtouchMdnsRecord> {
-  public id = 'soundtouch-mdns-match';
-  public source = 'mdns' as const;
-  public description = 'Recognize Bose SoundTouch zeroconf advertisements.';
-
-  public async matches(recordArg: ISoundtouchMdnsRecord, contextArg: IDiscoveryContext): Promise<IDiscoveryMatch> {
-    void contextArg;
-    const type = recordArg.type || '';
-    const txt = recordArg.txt || {};
-    const matched = normalizeMdnsType(type) === normalizeMdnsType(soundtouchMdnsType);
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'mDNS record is not a SoundTouch advertisement.' };
-    }
-
-    const id = valueForKey(txt, 'deviceId') || valueForKey(txt, 'deviceID') || valueForKey(txt, 'id') || recordArg.name;
-    return {
-      matched: true,
-      confidence: recordArg.host ? 'certain' : 'high',
-      reason: 'mDNS record matches Bose SoundTouch zeroconf metadata.',
-      normalizedDeviceId: id,
-      candidate: {
-        source: 'mdns',
-        integrationDomain: soundtouchDomain,
-        id,
-        host: recordArg.host,
-        port: recordArg.port || soundtouchDefaultPort,
-        name: recordArg.name,
-        manufacturer: 'Bose Corporation',
-        model: valueForKey(txt, 'type') || valueForKey(txt, 'model'),
-        macAddress: valueForKey(txt, 'mac') || valueForKey(txt, 'macAddress'),
-        metadata: { mdnsName: recordArg.name, mdnsType: type, txt },
-      },
-    };
-  }
-}
-
-export class SoundtouchManualMatcher implements IDiscoveryMatcher<ISoundtouchManualEntry> {
-  public id = 'soundtouch-manual-match';
-  public source = 'manual' as const;
-  public description = 'Recognize manual Bose SoundTouch setup entries.';
-
-  public async matches(inputArg: ISoundtouchManualEntry, contextArg: IDiscoveryContext): Promise<IDiscoveryMatch> {
-    void contextArg;
-    const haystack = `${inputArg.name || ''} ${inputArg.manufacturer || ''} ${inputArg.model || ''}`.toLowerCase();
-    const matched = Boolean(inputArg.host || inputArg.metadata?.soundtouch || haystack.includes('soundtouch') || haystack.includes('bose'));
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'Manual entry does not contain SoundTouch setup hints.' };
+import type { IDiscoveryCandidate, IDiscoveryMatch } from '../../core/types.js';
+import { readSoundtouchEndpoint, soundtouchKeys, soundtouchRecord, soundtouchText } from './soundtouch.validation.js';
+
+function matchSoundtouchCandidate(valueArg: unknown): IDiscoveryMatch {
+  try {
+    const input = soundtouchRecord(valueArg, 'selected candidate'); soundtouchKeys(input, ['source', 'integrationDomain', 'id', 'host', 'port', 'name', 'metadata']);
+    if (input.integrationDomain !== 'soundtouch' || input.source !== 'manual' && input.source !== 'custom') {
+      return { matched: false, confidence: 'low', reason: 'SoundTouch requires an explicitly selected manual/custom candidate.' };
     }
-
-    const id = inputArg.deviceId || inputArg.macAddress || inputArg.id || (inputArg.host ? `${inputArg.host}:${inputArg.port || soundtouchDefaultPort}` : undefined);
-    return {
-      matched: true,
-      confidence: inputArg.host ? 'high' : 'medium',
-      reason: 'Manual entry can start SoundTouch setup.',
-      normalizedDeviceId: id,
-      candidate: {
-        source: 'manual',
-        integrationDomain: soundtouchDomain,
-        id,
-        host: inputArg.host,
-        port: inputArg.port || soundtouchDefaultPort,
-        name: inputArg.name,
-        manufacturer: normalizedManufacturer(inputArg.manufacturer),
-        model: inputArg.model,
-        macAddress: inputArg.macAddress,
-        metadata: inputArg.metadata,
-      },
-    };
-  }
+    const metadata = soundtouchRecord(input.metadata, 'candidate metadata'); soundtouchKeys(metadata, ['type']);
+    const endpoint = readSoundtouchEndpoint(input.host, input.id, metadata.type, input.port);
+    const candidate: IDiscoveryCandidate = Object.freeze({ source: input.source, integrationDomain: 'soundtouch', id: endpoint.deviceId,
+      host: endpoint.host, port: endpoint.port, ...(input.name === undefined ? {} : { name: soundtouchText(input.name, 'candidate name') }),
+      metadata: Object.freeze({ type: endpoint.type }) });
+    return { matched: true, confidence: 'medium', reason: 'Selected endpoint/deviceID/type; live identity is verified during setup.', candidate, normalizedDeviceId: endpoint.deviceId };
+  } catch (errorArg) { return { matched: false, confidence: 'low', reason: errorArg instanceof Error ? errorArg.message : 'Invalid SoundTouch candidate.' }; }
 }
-
-export class SoundtouchCandidateValidator implements IDiscoveryValidator {
-  public id = 'soundtouch-candidate-validator';
-  public description = 'Validate Bose SoundTouch candidates.';
-
-  public async validate(candidateArg: IDiscoveryCandidate, contextArg: IDiscoveryContext): Promise<IDiscoveryMatch> {
-    void contextArg;
-    const metadata = candidateArg.metadata || {};
-    const matched = candidateArg.integrationDomain === soundtouchDomain
-      || includesSoundtouch(candidateArg.name)
-      || includesSoundtouch(candidateArg.model)
-      || includesBose(candidateArg.manufacturer)
-      || Boolean(metadata.soundtouch)
-      || normalizeMdnsType(stringMetadata(metadata.mdnsType) || '') === normalizeMdnsType(soundtouchMdnsType);
-
-    return {
-      matched,
-      confidence: matched && candidateArg.host ? 'high' : matched ? 'medium' : 'low',
-      reason: matched ? 'Candidate has Bose SoundTouch metadata.' : 'Candidate is not SoundTouch.',
-      candidate: matched ? { ...candidateArg, port: candidateArg.port || soundtouchDefaultPort } : undefined,
-      normalizedDeviceId: candidateArg.id || candidateArg.macAddress,
-    };
-  }
+/** Matching only; this subset performs no network discovery. */
+export function createSoundtouchDiscoveryDescriptor(): DiscoveryDescriptor {
+  return new DiscoveryDescriptor({ integrationDomain: 'soundtouch', displayName: 'Bose SoundTouch' })
+    .addMatcher({ id: 'soundtouch-manual-match', source: 'manual', matches: async (inputArg) => matchSoundtouchCandidate(inputArg) })
+    .addMatcher({ id: 'soundtouch-custom-match', source: 'custom', matches: async (inputArg) => matchSoundtouchCandidate(inputArg) })
+    .addValidator({ id: 'soundtouch-selected-endpoint', validate: async (candidateArg) => matchSoundtouchCandidate(candidateArg) });
 }
-
-export const createSoundtouchDiscoveryDescriptor = (): DiscoveryDescriptor => {
-  return new DiscoveryDescriptor({ integrationDomain: soundtouchDomain, displayName: 'Bose SoundTouch' })
-    .addMatcher(new SoundtouchMdnsMatcher())
-    .addMatcher(new SoundtouchManualMatcher())
-    .addValidator(new SoundtouchCandidateValidator());
-};
-
-const valueForKey = (recordArg: Record<string, string | undefined> | undefined, keyArg: string): string | undefined => {
-  if (!recordArg) {
-    return undefined;
-  }
-  const lowerKey = keyArg.toLowerCase();
-  for (const [key, value] of Object.entries(recordArg)) {
-    if (key.toLowerCase() === lowerKey) {
-      return value;
-    }
-  }
-  return undefined;
-};
-
-const normalizeMdnsType = (valueArg: string): string => valueArg.toLowerCase().replace(/\.$/, '');
-
-const normalizedManufacturer = (valueArg: string | undefined): string => {
-  if (!valueArg || valueArg.toLowerCase().includes('bose')) {
-    return 'Bose Corporation';
-  }
-  return valueArg;
-};
-
-const includesSoundtouch = (valueArg: string | undefined): boolean => Boolean(valueArg?.toLowerCase().includes('soundtouch'));
-
-const includesBose = (valueArg: string | undefined): boolean => Boolean(valueArg?.toLowerCase().includes('bose'));
-
-const stringMetadata = (valueArg: unknown): string | undefined => typeof valueArg === 'string' ? valueArg : undefined;