@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/sonos/sonos.mapper.ts

@@ -4,17 +4,18 @@ import type { ISonosSnapshot } from './sonos.types.js';
 
 export class SonosMapper {
   public static toDevices(snapshotArg: ISonosSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
-    const updatedAt = new Date().toISOString();
+    const updatedAt = snapshotArg.observedAt;
     const deviceId = this.deviceId(snapshotArg);
     const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
-      { id: 'playback', capability: 'media', name: 'Playback', readable: true, writable: true },
+      { id: 'playback', capability: 'media', name: 'Playback', readable: true,
+        writable: snapshotArg.group.coordinatorUid === snapshotArg.speakerInfo.uid },
       { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: true, unit: '%' },
       { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: true },
     ];
     const state: plugins.shxInterfaces.data.IDeviceState[] = [
       { featureId: 'playback', value: this.playbackState(snapshotArg), updatedAt },
-      { featureId: 'volume', value: snapshotArg.volume ?? null, updatedAt },
-      { featureId: 'muted', value: snapshotArg.muted ?? null, updatedAt },
+      { featureId: 'volume', value: snapshotArg.volume, updatedAt },
+      { featureId: 'muted', value: snapshotArg.muted, updatedAt },
     ];
     if (snapshotArg.positionInfo.title) {
       features.push({ id: 'current_title', capability: 'media', name: 'Current title', readable: true, writable: false });
@@ -36,13 +37,17 @@ export class SonosMapper {
         serialNumber: snapshotArg.speakerInfo.serialNumber,
         softwareVersion: snapshotArg.speakerInfo.softwareVersion,
         householdId: snapshotArg.speakerInfo.householdId,
+        groupId: snapshotArg.group.id,
+        coordinatorUid: snapshotArg.group.coordinatorUid,
+        groupMemberUids: [...snapshotArg.group.memberUids],
+        stateSource: 'local_poll',
       },
     }];
   }
 
   public static toEntities(snapshotArg: ISonosSnapshot): IIntegrationEntity[] {
     return [{
-      id: `media_player.${this.slug(snapshotArg.speakerInfo.zoneName)}`,
+      id: this.entityId(snapshotArg.speakerInfo.uid),
       uniqueId: `sonos_${this.slug(snapshotArg.speakerInfo.uid)}`,
       integrationDomain: 'sonos',
       deviceId: this.deviceId(snapshotArg),
@@ -50,7 +55,7 @@ export class SonosMapper {
       name: snapshotArg.speakerInfo.zoneName,
       state: this.playbackState(snapshotArg),
       attributes: {
-        volumeLevel: typeof snapshotArg.volume === 'number' ? snapshotArg.volume / 100 : undefined,
+        volumeLevel: snapshotArg.volume / 100,
         muted: snapshotArg.muted,
         mediaTitle: snapshotArg.positionInfo.title,
         mediaArtist: snapshotArg.positionInfo.artist,
@@ -59,6 +64,11 @@ export class SonosMapper {
         mediaPosition: snapshotArg.positionInfo.relativeTime,
         mediaUri: snapshotArg.positionInfo.trackUri,
         albumArtUri: snapshotArg.positionInfo.albumArtUri,
+        groupId: snapshotArg.group.id,
+        coordinatorUid: snapshotArg.group.coordinatorUid,
+        groupMemberUids: [...snapshotArg.group.memberUids],
+        observedAt: snapshotArg.observedAt,
+        stateSource: 'local_poll',
       },
       available: true,
     }];
@@ -66,22 +76,28 @@ export class SonosMapper {
 
   private static playbackState(snapshotArg: ISonosSnapshot): string {
     const state = snapshotArg.transportInfo.currentTransportState;
-    if (state === 'PLAYING' || state === 'TRANSITIONING') {
+    if (state === 'PLAYING') {
       return 'playing';
     }
+    if (state === 'TRANSITIONING') return 'buffering';
     if (state === 'PAUSED_PLAYBACK') {
-      return snapshotArg.positionInfo.title ? 'paused' : 'idle';
+      return 'paused';
     }
-    if (state === 'STOPPED') {
-      return snapshotArg.positionInfo.title ? 'paused' : 'idle';
-    }
-    return 'idle';
+    if (state === 'STOPPED') return 'stopped';
+    if (state === 'NO_MEDIA_PRESENT') return 'idle';
+    if (state === 'RECORDING') return 'recording';
+    if (state === 'PAUSED_RECORDING') return 'paused_recording';
+    return 'unknown';
   }
 
-  private static deviceId(snapshotArg: ISonosSnapshot): string {
+  public static deviceId(snapshotArg: ISonosSnapshot): string {
     return `sonos.player.${this.slug(snapshotArg.speakerInfo.uid)}`;
   }
 
+  public static entityId(uid: string): string {
+    return `media_player.sonos_${this.slug(uid)}`;
+  }
+
   private static slug(valueArg: string): string {
     return valueArg.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'sonos';
   }

package/ts/integrations/sonos/sonos.matchers.ts

@@ -0,0 +1,83 @@
+import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
+import { isSonosDataRecord, normalizeSonosConfig, normalizeSonosUid } from './sonos.config.js';
+import type { ISonosManualEntry, ISonosMdnsRecord, ISonosSsdpRecord } from './sonos.types.js';
+
+const sonosUpnpSt = 'urn:schemas-upnp-org:device:ZonePlayer:1';
+const noMatch = (reason: string): IDiscoveryMatch => ({ matched: false, confidence: 'low', reason });
+
+function candidateMatch(source: IDiscoveryCandidate['source'], host: unknown, port: unknown, uid?: unknown): IDiscoveryMatch {
+  try {
+    if (typeof host !== 'string' || typeof port !== 'number' || (uid !== undefined && typeof uid !== 'string')) throw new Error('Sonos candidate fields are invalid.');
+    const config = normalizeSonosConfig({ host, port, ...(uid ? { expectedUid: uid } : {}) });
+    return {
+      matched: true, confidence: uid ? 'high' : 'medium', reason: 'Candidate identifies a local Sonos endpoint; setup verifies the renderer.',
+      normalizedDeviceId: config.expectedUid,
+      candidate: { source, integrationDomain: 'sonos', host: config.host, port: config.port,
+        ...(config.expectedUid ? { id: config.expectedUid } : {}), manufacturer: 'Sonos' },
+    };
+  } catch {
+    return noMatch('Sonos candidate has an invalid endpoint or player identity.');
+  }
+}
+
+export class SonosSsdpMatcher implements IDiscoveryMatcher<ISonosSsdpRecord> {
+  public readonly id = 'sonos-ssdp-match';
+  public readonly source = 'ssdp' as const;
+  public readonly description = 'Recognize Sonos ZonePlayer SSDP advertisements.';
+
+  public async matches(record: ISonosSsdpRecord): Promise<IDiscoveryMatch> {
+    if (!isSonosDataRecord(record) || (record.headers !== undefined && !isSonosDataRecord(record.headers))) return noMatch('SSDP record contains invalid fields.');
+    const st = record.st ?? record.headers?.st ?? record.headers?.ST;
+    const usn = record.usn ?? record.headers?.usn ?? record.headers?.USN;
+    const location = record.location ?? record.headers?.location ?? record.headers?.LOCATION;
+    if (st !== sonosUpnpSt || typeof usn !== 'string' || typeof location !== 'string') return noMatch('SSDP record is not a Sonos ZonePlayer.');
+    try {
+      const identity = usn.match(/^uuid:([^:]+)(?:::urn:schemas-upnp-org:device:ZonePlayer:1)?$/i)?.[1];
+      const uid = normalizeSonosUid(identity);
+      const url = new URL(location);
+      if (url.protocol !== 'http:' || url.username || url.password || url.search || url.hash || url.pathname !== '/xml/device_description.xml') {
+        return noMatch('Sonos SSDP description must use an uncredentialed local HTTP device-description URL.');
+      }
+      return candidateMatch('ssdp', url.hostname, Number(url.port || 80), uid);
+    } catch {
+      return noMatch('Sonos SSDP advertisement has an invalid URL or UUID.');
+    }
+  }
+}
+
+export class SonosMdnsMatcher implements IDiscoveryMatcher<ISonosMdnsRecord> {
+  public readonly id = 'sonos-mdns-match';
+  public readonly source = 'mdns' as const;
+  public readonly description = 'Recognize explicit Sonos mDNS services.';
+
+  public async matches(record: ISonosMdnsRecord): Promise<IDiscoveryMatch> {
+    if (!isSonosDataRecord(record) || (record.txt !== undefined && !isSonosDataRecord(record.txt))) return noMatch('mDNS record contains invalid fields.');
+    if (typeof record.type !== 'string' || record.type.toLowerCase() !== '_sonos._tcp.local.' || !record.host) return noMatch('mDNS service is not Sonos.');
+    return candidateMatch('mdns', record.host, record.port ?? 1400, record.txt?.id ?? record.txt?.uid);
+  }
+}
+
+export class SonosManualMatcher implements IDiscoveryMatcher<ISonosManualEntry> {
+  public readonly id = 'sonos-manual-match';
+  public readonly source = 'manual' as const;
+  public readonly description = 'Recognize explicit manual Sonos setup entries.';
+
+  public async matches(input: ISonosManualEntry): Promise<IDiscoveryMatch> {
+    if (!isSonosDataRecord(input) || (input.metadata !== undefined && !isSonosDataRecord(input.metadata))) return noMatch('Manual record contains invalid fields.');
+    if (!input.host || !((typeof input.model === 'string' && input.model.toLowerCase().includes('sonos')) || input.metadata?.sonos === true || (typeof input.id === 'string' && input.id.startsWith('RINCON_')))) {
+      return noMatch('Manual entry requires an explicit Sonos hint and endpoint.');
+    }
+    return candidateMatch('manual', input.host, input.port ?? 1400, input.id);
+  }
+}
+
+export class SonosCandidateValidator implements IDiscoveryValidator {
+  public readonly id = 'sonos-candidate-validator';
+  public readonly description = 'Validate and allowlist Sonos candidate fields.';
+
+  public async validate(candidate: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
+    if (!isSonosDataRecord(candidate) || !['manual', 'ssdp', 'mdns'].includes(candidate.source)) return noMatch('Sonos candidate contains invalid fields or source.');
+    if (candidate.integrationDomain !== 'sonos' || !candidate.host) return noMatch('Candidate does not belong to Sonos or lacks an endpoint.');
+    return candidateMatch(candidate.source, candidate.host, candidate.port ?? 1400, candidate.id);
+  }
+}

package/ts/integrations/sonos/sonos.topology.ts

@@ -0,0 +1,54 @@
+import { normalizeSonosUid } from './sonos.config.js';
+import type { ISonosGroup } from './sonos.types.js';
+import { readSonosXmlElement } from './sonos.xml.js';
+
+export function parseSonosGroup(document: Record<string, unknown>, selectedUid: string): ISonosGroup {
+  selectedUid = normalizeSonosUid(selectedUid);
+  const root = readSonosXmlElement(readSonosXmlElement(document, 'topology document').ZoneGroupState, 'ZoneGroupState');
+  const container = readSonosXmlElement(root.ZoneGroups, 'ZoneGroups');
+  const groups = list(container.ZoneGroup);
+  if (!groups.length || groups.length > 128) throw new Error('Sonos topology must contain from 1 to 128 groups.');
+  const knownMembers = new Set<string>();
+  const groupIds = new Set<string>();
+  let selected: ISonosGroup | undefined;
+  for (const value of groups) {
+    const group = readSonosXmlElement(value, 'ZoneGroup');
+    const id = text(group['@_ID'], 'group ID');
+    if (id.length > 128 || /[\s\x00-\x1f]/.test(id) || groupIds.has(id)) throw new Error('Sonos group ID is invalid or duplicated.');
+    groupIds.add(id);
+    const coordinatorUid = normalizeSonosUid(group['@_Coordinator']);
+    const members = list(group.ZoneGroupMember);
+    if (!members.length || members.length > 128) throw new Error('Sonos group must contain from 1 to 128 members.');
+    const memberUids: string[] = [];
+    for (const value of members) {
+      const member = readSonosXmlElement(value, 'ZoneGroupMember');
+      const uid = normalizeSonosUid(member['@_UUID']);
+      addMember(uid, memberUids, knownMembers);
+      for (const value of list(member.Satellite)) {
+        const satellite = readSonosXmlElement(value, 'Satellite');
+        const satelliteUid = normalizeSonosUid(satellite['@_UUID']);
+        if (satelliteUid === selectedUid) throw new Error('Select the parent Sonos renderer instead of a bonded satellite.');
+        addMember(satelliteUid, memberUids, knownMembers);
+      }
+    }
+    if (!memberUids.includes(coordinatorUid)) throw new Error('Sonos group coordinator is not a member.');
+    if (memberUids.includes(selectedUid)) selected = { id, coordinatorUid, memberUids: memberUids.sort() };
+  }
+  if (!selected) throw new Error('Selected Sonos renderer is absent from the topology.');
+  return selected;
+}
+
+function addMember(uid: string, members: string[], known: Set<string>): void {
+  if (known.has(uid) || known.size >= 128) throw new Error('Sonos topology contains a duplicate or too many players.');
+  known.add(uid);
+  members.push(uid);
+}
+
+function list(value: unknown): unknown[] {
+  return value === undefined ? [] : Array.isArray(value) ? value : [value];
+}
+
+function text(value: unknown, name: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`Sonos ${name} must be nonempty text.`);
+  return value;
+}

package/ts/integrations/sonos/sonos.types.ts

@@ -1,11 +1,10 @@
 export interface ISonosConfig {
-  host?: string;
+  host: string;
   port?: number;
-  speakerInfo?: ISonosSpeakerInfo;
-  transportInfo?: ISonosTransportInfo;
-  positionInfo?: ISonosPositionInfo;
-  volume?: number;
-  muted?: boolean;
+  expectedUid?: string;
+  timeoutMs?: number;
+  maxResponseBytes?: number;
+  pollIntervalMs?: number;
 }
 
 export interface ISonosSpeakerInfo {
@@ -41,8 +40,21 @@ export interface ISonosSnapshot {
   speakerInfo: ISonosSpeakerInfo;
   transportInfo: ISonosTransportInfo;
   positionInfo: ISonosPositionInfo;
-  volume?: number;
-  muted?: boolean;
+  volume: number;
+  muted: boolean;
+  group: ISonosGroup;
+  observedAt: string;
+}
+
+export interface ISonosGroup {
+  id: string;
+  coordinatorUid: string;
+  memberUids: string[];
+}
+
+export interface ISonosMediaOptions {
+  title?: string;
+  mimeType?: string;
 }
 
 export interface ISonosSsdpRecord {

package/ts/integrations/sonos/sonos.xml.ts

@@ -0,0 +1,19 @@
+import { isSonosDataRecord } from './sonos.config.js';
+
+export function readSonosXmlElement(value: unknown, name: string): Record<string, unknown> {
+  if (!isSonosDataRecord(value)) throw new Error(`Sonos ${name} must be an XML element.`);
+  return value;
+}
+
+export function readSonosOptionalText(value: Record<string, unknown>, name: string): string | undefined {
+  const text = value[name];
+  if (text === undefined) return undefined;
+  if (typeof text !== 'string') throw new Error(`Sonos ${name} must be text.`);
+  return text;
+}
+
+export function readSonosText(value: Record<string, unknown>, name: string): string {
+  const text = readSonosOptionalText(value, name);
+  if (!text?.trim()) throw new Error(`Sonos ${name} is missing.`);
+  return text.trim();
+}

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/).

package/ts/integrations/tasmota/tasmota.classes.integration.ts

@@ -1,27 +1,30 @@
-import { DescriptorOnlyIntegration } from '../../core/classes.descriptoronlyintegration.js';
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import type { IIntegrationSetupContext } from '../../core/types.js';
+import { createTasmotaDiscoveryDescriptor, TasmotaConfigFlow } from './tasmota.discovery.js';
+import { TasmotaRuntime } from './tasmota.classes.runtime.js';
+import type { IHomeAssistantTasmotaConfig } from './tasmota.types.js';
 
-export class HomeAssistantTasmotaIntegration extends DescriptorOnlyIntegration {
-  constructor() {
-    super({
-      domain: "tasmota",
-      displayName: "Tasmota",
-      status: 'descriptor-only',
-      metadata: {
-  "source": "home-assistant/core",
-  "upstreamPath": "homeassistant/components/tasmota",
-  "upstreamDomain": "tasmota",
-  "iotClass": "local_push",
-  "requirements": [
-    "HATasmota==0.10.1"
-  ],
-  "dependencies": [
-    "mqtt"
-  ],
-  "afterDependencies": [],
-  "codeowners": [
-    "@emontnemery"
-  ]
-},
-    });
+export class HomeAssistantTasmotaIntegration extends BaseIntegration<IHomeAssistantTasmotaConfig> {
+  public readonly domain = 'tasmota';
+  public readonly displayName = 'Tasmota';
+  public readonly status = 'control-runtime' as const;
+  public readonly discoveryDescriptor = createTasmotaDiscoveryDescriptor();
+  public readonly configFlow = new TasmotaConfigFlow();
+  public readonly metadata = {
+    source: 'home-assistant/core',
+    upstreamPath: 'homeassistant/components/tasmota',
+    upstreamDomain: 'tasmota',
+    iotClass: 'local_push',
+    transport: 'mqtt',
+    scope: 'selected-device-relays-brightness-sensors',
+  };
+
+  public async setup(configArg: IHomeAssistantTasmotaConfig, contextArg: IIntegrationSetupContext): Promise<TasmotaRuntime> {
+    contextArg.abortSignal?.throwIfAborted();
+    const runtime = new TasmotaRuntime(configArg);
+    await runtime.start(contextArg.abortSignal);
+    return runtime;
   }
+
+  public async destroy(): Promise<void> {}
 }