@smarthome.exchange/integrations 0.2.0 → 2.0.0

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

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

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

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

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

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

package/ts/integrations/tasmota/index.ts

@@ -1,2 +1,6 @@
 export * from './tasmota.classes.integration.js';
 export * from './tasmota.types.js';
+export * from './tasmota.classes.runtime.js';
+export * from './tasmota.config.js';
+export * from './tasmota.discovery.js';
+export * from './tasmota.mapper.js';

package/ts/integrations/tasmota/readme.md

@@ -0,0 +1,33 @@
+# 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.
+
+```typescript
+import { HomeAssistantTasmotaIntegration } from '@smarthome.exchange/integrations';
+
+const runtime = await new HomeAssistantTasmotaIntegration().setup({
+  broker: { host: 'mqtt.home', protocol: 'mqtts', username, password },
+  devices: [{ topic: 'desk', relays: [1], brightness: true }],
+  initialSnapshotTimeoutMs: 10_000,
+}, { 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();
+}
+```
+
+`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.
+
+Broker loss or `Offline` LWT blocks writes immediately. Reconnection and `Online` LWT require another fresh state query before readiness returns. MQTT owns reconnection and subscription restoration. Runtime destruction cancels pending work, closes the owned transport and removes event listeners; repeated destruction is safe. Caller abort signals are accepted by setup, snapshots, subscriptions and feature writes.
+
+Relay features are `power_<relay-number>`. Sensor telemetry is read-only; numeric, boolean and string values are mapped from `SENSOR` and `STATUS10.StatusSNS`, with encoded path identifiers such as `sensor_ENERGY/Power`. Reads return authoritative device messages. Successful writes acknowledge transport acceptance, and never optimistically change readable state. Commands target only explicitly selected devices and controls, use QoS 0 and always disable retain.
+
+Automatic Tasmota discovery, multi-channel dimmers, shutters, fans, IR commands, device firmware configuration, Berry, Zigbee and Bluetooth bridges are outside this slice. Fixture tests verify the local MQTT lifecycle; physical devices still require acceptance testing.
+
+Protocol sources: [Tasmota MQTT](https://tasmota.github.io/docs/MQTT/), [commands](https://tasmota.github.io/docs/Commands/), and [JSON status responses](https://tasmota.github.io/docs/JSON-Status-Responses/).