@smarthome.exchange/integrations 1.0.0 → 3.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/tasmota/readme.md

@@ -1,25 +1,36 @@
 # Native Tasmota runtime
 
-This integration connects directly to a MQTT broker through the package's shared `MqttClient`. Configure each Tasmota device's broker and unique `Topic` before setup. No Home Assistant connection is required.
+This integration connects directly to a MQTT broker through the package's shared `MqttSession`, which owns credential resolution and its `MqttClient` transport. Configure each Tasmota device's broker and unique `Topic` before setup. No Home Assistant connection is required.
 
 ```typescript
 import { HomeAssistantTasmotaIntegration } from '@smarthome.exchange/integrations';
 
-const runtime = await new HomeAssistantTasmotaIntegration().setup({
-  broker: { host: 'mqtt.home', protocol: 'mqtts', username, password },
+const integration = new HomeAssistantTasmotaIntegration({ enableControls: true });
+const runtime = await integration.setup({
+  homeId: selectedHomeId,
+  authentication: { mode: 'credential-reference', credentialRef: 'broker-main' },
+  broker: { host: 'mqtt.home', protocol: 'mqtts' },
   devices: [{ topic: 'desk', relays: [1], brightness: true }],
   initialSnapshotTimeoutMs: 10_000,
-}, { abortSignal });
+}, { homeId: selectedHomeId, configStore: borrowedEncryptedStore, abortSignal });
 
 try {
   const [device] = await runtime.devices();
   const feature = device.features.find((feature) => feature.id === 'power_1');
   if (feature) await runtime.writeFeature({ device, feature, value: false });
 } finally {
-  await runtime.destroy();
+  await integration.destroy();
 }
 ```
 
+The embedding host must independently supply its selected `homeId` in setup and config-flow context. The configured home must match it. An optional constructor `homeId` adds an immutable constraint; without it, the first admitted setup or flow fixes the instance's home even if setup fails. Discovery metadata, editable values and store scope cannot select the home. Default registry construction remains inert. Entity identifiers include the captured host home. This contract relies on the embedding host's authorization boundary; a home string is not an authentication token.
+
+Authentication is explicit: `authentication: { mode: 'anonymous' }` selects a broker requiring no authentication. Otherwise, a credential reference requires an actual matching borrowed `NoSqlConfigStore` or a runtime-only constructor `credentialResolver`. Legacy plaintext broker username/password configuration fails with an explicit reconfiguration requirement. Flow secret inputs are transient; an admitted encrypted store creates an insert-only reference and the returned configuration contains no secrets. A cancelled late credential write is joined and removed before flow shutdown completes. Anonymous mode never substitutes for a missing or failed credential source.
+
+A constructor resolver receives frozen `{ homeId, credentialRef, broker: { host, port, protocol }, signal, deadlineMonotonicMs }`; the deadline uses `performance.now()`. It returns a plain version1 record containing exactly that broker identity and optional username/password or TLS ca/cert/key/servername. Certificate and private key must be paired; TLS material requires mqtts. A result for another broker is rejected before connecting. Tasmota adapts this broker-bound contract to the shared MQTT session resolver. The session fences startup on cancellation or deadline and retains the actual resolver promise for shutdown, so an ignored cancellation or late result cannot connect. Resolver failures are sanitized and remain observable through session cleanup; explicit `retryCleanup()` acknowledges drained failures without resolving credentials again. The caller owns its resolver, store, database and key provider; the integration closes none of them.
+
+Relay and brightness writes require the embedding owner's runtime-only constructor `enableControls: true`. This permission is not accepted from config forms. Without it, controls remain readable and writes fail before publishing. Every admitted command shares the owner's bounded capacity with pending setups, flows, runtimes and failed cleanup handles (default16, adjustable with constructor `capacity`). Integration destruction is terminal, drains every owned runtime and pending operation, and returns a stable close promise. Runtime destruction releases its owned lease. Failed cleanup remains retained; `integration.retryCleanup()` retries resource cleanup only, never setup, authentication, subscription or control commands.
+
 `relays` defaults to `[1]`; use `[]` for sensor-only devices. `brightness: true` enables the single-channel `Dimmer` command with integer percentage values from 0 through 100. Device identifiers default to `tasmota:<encoded-topic>` and can be assigned explicitly through `id`. `fullTopic` defaults to `%prefix%/%topic%/`; custom patterns must end in `/` and include each token exactly once. Only those two substitution tokens are supported. Custom `prefixes` specify all three command, status and telemetry prefixes. `powerOnPayload` and `powerOffPayload` describe customized `StateText` output; commands still use the standard `ON` and `OFF` arguments.
 
 Setup shares one deadline across the broker connection, subscription acknowledgments, state queries and first fresh snapshots. It requests `State` and `Status 10` for every selected device. A fresh nonretained `STATE`, `STATUS11` or complete `RESULT` state response must report every configured control before that device becomes ready. Retained state can provide an offline snapshot, but cannot establish readiness or overwrite ready state. The protocol does not correlate MQTT 3.1.1 command responses; readiness establishes current nonretained state after a query, rather than proving which request caused the message.