@smarthome.exchange/integrations 0.2.0 → 2.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();
+}