@smarthome.exchange/integrations 1.0.0 → 3.0.0

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

@@ -8,9 +8,10 @@ export class SonosMapper {
     const deviceId = this.deviceId(snapshotArg);
     const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
       { 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 },
+        writable: snapshotArg.controlAllowed && snapshotArg.group.coordinatorUid === snapshotArg.speakerInfo.uid
+          && snapshotArg.capabilities.transportActions.some((action) => ['Play', 'Pause', 'Stop'].includes(action) && snapshotArg.capabilities.declaredTransportActions.includes(action)) },
+      { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: snapshotArg.controlAllowed && snapshotArg.capabilities.volumeWritable, unit: '%' },
+      { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: snapshotArg.controlAllowed && snapshotArg.capabilities.muteWritable },
     ];
     const state: plugins.shxInterfaces.data.IDeviceState[] = [
       { featureId: 'playback', value: this.playbackState(snapshotArg), updatedAt },
@@ -33,6 +34,7 @@ export class SonosMapper {
       features,
       state,
       metadata: {
+        homeId: snapshotArg.homeId,
         uid: snapshotArg.speakerInfo.uid,
         serialNumber: snapshotArg.speakerInfo.serialNumber,
         softwareVersion: snapshotArg.speakerInfo.softwareVersion,
@@ -41,20 +43,23 @@ export class SonosMapper {
         coordinatorUid: snapshotArg.group.coordinatorUid,
         groupMemberUids: [...snapshotArg.group.memberUids],
         stateSource: 'local_poll',
+        physicalEffectConfirmed: false,
+        capabilities: structuredClone(snapshotArg.capabilities),
       },
     }];
   }
 
   public static toEntities(snapshotArg: ISonosSnapshot): IIntegrationEntity[] {
     return [{
-      id: this.entityId(snapshotArg.speakerInfo.uid),
-      uniqueId: `sonos_${this.slug(snapshotArg.speakerInfo.uid)}`,
+      id: this.entityId(snapshotArg.homeId, snapshotArg.speakerInfo.uid),
+      uniqueId: this.deviceId(snapshotArg),
       integrationDomain: 'sonos',
       deviceId: this.deviceId(snapshotArg),
       platform: 'media_player',
       name: snapshotArg.speakerInfo.zoneName,
       state: this.playbackState(snapshotArg),
       attributes: {
+        homeId: snapshotArg.homeId,
         volumeLevel: snapshotArg.volume / 100,
         muted: snapshotArg.muted,
         mediaTitle: snapshotArg.positionInfo.title,
@@ -91,11 +96,11 @@ export class SonosMapper {
   }
 
   public static deviceId(snapshotArg: ISonosSnapshot): string {
-    return `sonos.player.${this.slug(snapshotArg.speakerInfo.uid)}`;
+    return `sonos.player.${encodeURIComponent(snapshotArg.homeId)}.${this.slug(snapshotArg.speakerInfo.uid)}`;
   }
 
-  public static entityId(uid: string): string {
-    return `media_player.sonos_${this.slug(uid)}`;
+  public static entityId(homeId: string, uid: string): string {
+    return `media_player.sonos.${encodeURIComponent(homeId)}.${this.slug(uid)}`;
   }
 
   private static slug(valueArg: string): string {

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

@@ -1,5 +1,5 @@
 import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
-import { isSonosDataRecord, normalizeSonosConfig, normalizeSonosUid } from './sonos.config.js';
+import { isSonosDataRecord, normalizeSonosEndpoint, normalizeSonosUid } from './sonos.config.js';
 import type { ISonosManualEntry, ISonosMdnsRecord, ISonosSsdpRecord } from './sonos.types.js';
 
 const sonosUpnpSt = 'urn:schemas-upnp-org:device:ZonePlayer:1';
@@ -8,7 +8,7 @@ const noMatch = (reason: string): IDiscoveryMatch => ({ matched: false, confiden
 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 } : {}) });
+    const config = normalizeSonosEndpoint({ 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,

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

@@ -1,4 +1,4 @@
-export interface ISonosConfig {
+export interface ISonosEndpointConfig {
   host: string;
   port?: number;
   expectedUid?: string;
@@ -7,6 +7,16 @@ export interface ISonosConfig {
   pollIntervalMs?: number;
 }
 
+export interface ISonosConfig extends ISonosEndpointConfig {
+  homeId: string;
+}
+
+/** Host-owned permission; never accepted from stored config, a form or discovery. */
+export interface ISonosOwnerOptions {
+  readonly homeId?: string;
+  readonly allowControl?: boolean;
+}
+
 export interface ISonosSpeakerInfo {
   uid: string;
   zoneName: string;
@@ -37,6 +47,8 @@ export interface ISonosPositionInfo {
 }
 
 export interface ISonosSnapshot {
+  homeId: string;
+  controlAllowed: boolean;
   speakerInfo: ISonosSpeakerInfo;
   transportInfo: ISonosTransportInfo;
   positionInfo: ISonosPositionInfo;
@@ -44,6 +56,23 @@ export interface ISonosSnapshot {
   muted: boolean;
   group: ISonosGroup;
   observedAt: string;
+  capabilities: ISonosCapabilities;
+}
+
+export interface ISonosCapabilities {
+  readonly transportActions: readonly string[];
+  readonly declaredTransportActions: readonly string[];
+  readonly volumeWritable: boolean;
+  readonly muteWritable: boolean;
+}
+
+export interface ISonosControlResult {
+  readonly acknowledgedActions: readonly string[];
+  readonly snapshot: ISonosSnapshot;
+  readonly outcome: 'observed-target' | 'observed-different' | 'observed-state';
+  readonly requestedValue?: string | number | boolean;
+  readonly observedValue?: string | number | boolean;
+  readonly physicalEffectConfirmed: false;
 }
 
 export interface ISonosGroup {