homebridge-yoto 0.0.39 → 0.0.41

package/lib/platform.js

@@ -5,11 +5,21 @@
 /** @import { API, DynamicPlatformPlugin, Logger, PlatformAccessory, PlatformConfig, Service, Characteristic } from 'homebridge' */
 /** @import { YotoDevice } from 'yoto-nodejs-client/lib/api-endpoints/devices.js' */
 /** @import { YotoDeviceModel } from 'yoto-nodejs-client' */
+/** @import { PlaybackAccessoryConfig } from './service-config.js' */
+/** @import { CardControlConfig } from './card-controls.js' */
 
 /**
  * Context stored in PlatformAccessory for Yoto devices
  * @typedef {Object} YotoAccessoryContext
  * @property {YotoDevice} device - Device metadata from Yoto API
+ * @property {'device'} [type] - Accessory type marker
+ */
+
+/**
+ * Context stored in PlatformAccessory for card control accessories
+ * @typedef {Object} YotoCardAccessoryContext
+ * @property {CardControlConfig} cardControl - Card control configuration
+ * @property {'card-control'} type - Accessory type marker
  */
 
 import { readFile, writeFile } from 'node:fs/promises'
@@ -21,7 +31,11 @@ import {
   DEFAULT_CLIENT_ID,
 } from './settings.js'
 import { YotoPlayerAccessory } from './accessory.js'
+import { YotoSpeakerAccessory } from './speaker-accessory.js'
+import { YotoCardControlAccessory } from './card-control-accessory.js'
 import { sanitizeName } from './sanitize-name.js'
+import { getPlaybackAccessoryConfig } from './service-config.js'
+import { getCardControlConfigs } from './card-controls.js'
 
 /**
  * Yoto Platform implementation
@@ -35,8 +49,13 @@ export class YotoPlatform {
   /** @type {API} */ api
   /** @type {typeof Service} */ Service
   /** @type {typeof Characteristic} */ Characteristic
+  /** @type {PlaybackAccessoryConfig} */ playbackAccessoryConfig
   /** @type {Map<string, PlatformAccessory<YotoAccessoryContext>>} */ accessories = new Map()
+  /** @type {Map<string, PlatformAccessory<YotoAccessoryContext>>} */ speakerAccessories = new Map()
+  /** @type {Map<string, PlatformAccessory<YotoCardAccessoryContext>>} */ cardAccessories = new Map()
   /** @type {Map<string, YotoPlayerAccessory>} */ accessoryHandlers = new Map()
+  /** @type {Map<string, YotoSpeakerAccessory>} */ speakerAccessoryHandlers = new Map()
+  /** @type {Map<string, YotoCardControlAccessory>} */ cardAccessoryHandlers = new Map()
   /** @type {YotoAccount | null} */ yotoAccount = null
   /** @type {string} */ sessionId = randomUUID()
 
@@ -51,6 +70,7 @@ export class YotoPlatform {
     this.api = api
     this.Service = api.hap.Service
     this.Characteristic = api.hap.Characteristic
+    this.playbackAccessoryConfig = getPlaybackAccessoryConfig(config)
 
     log.debug('Finished initializing platform:', config.name)
 
@@ -107,12 +127,20 @@ export class YotoPlatform {
       }
     })
 
+    const formatError = (/** @type {unknown} */ error) => (
+      error instanceof Error ? (error.stack || error.message) : String(error)
+    )
+
     // Listen to account-level events
     this.yotoAccount.on('error', ({ error, context }) => {
+      const details = formatError(error)
       if (context.deviceId) {
-        log.error(`Device error [${context.deviceId} ${context.operation} ${context.source}]:`, error.message)
+        const label = this.formatDeviceLabel(context.deviceId)
+        log.error(`Device error [${label} ${context.operation} ${context.source}]:`, details)
+        log.debug('Device error context:', context)
       } else {
-        log.error('Account error:', error.message)
+        log.error('Account error:', details)
+        log.debug('Account error context:', context)
       }
     })
 
@@ -141,9 +169,22 @@ export class YotoPlatform {
    * @param {PlatformAccessory} accessory - Cached accessory
    */
   configureAccessory (accessory) {
-    const { log, accessories } = this
+    const { log, accessories, cardAccessories } = this
     log.debug('Loading accessory from cache:', accessory.displayName)
 
+    const context = accessory.context
+    const record = context && typeof context === 'object'
+      ? /** @type {Record<string, unknown>} */ (context)
+      : null
+    const accessoryType = record && typeof record['type'] === 'string'
+      ? record['type']
+      : undefined
+
+    if (accessoryType === 'card-control' || record?.['cardControl']) {
+      cardAccessories.set(accessory.UUID, /** @type {PlatformAccessory<YotoCardAccessoryContext>} */ (accessory))
+      return
+    }
+
     // Add to our tracking map (cast to our typed version)
     accessories.set(accessory.UUID, /** @type {PlatformAccessory<YotoAccessoryContext>} */ (accessory))
   }
@@ -164,7 +205,8 @@ export class YotoPlatform {
       this.yotoAccount.on('deviceAdded', async ({ deviceId }) => {
         const deviceModel = this.yotoAccount?.getDevice(deviceId)
         if (!deviceModel) {
-          this.log.warn(`Device added but no model found for ${deviceId}`)
+          const label = this.formatDeviceLabel(deviceId)
+          this.log.warn(`Device added but no model found for ${label}`)
           return
         }
 
@@ -174,29 +216,23 @@ export class YotoPlatform {
       })
 
       this.yotoAccount.on('deviceRemoved', ({ deviceId }) => {
-        this.log.debug(`Device removed: ${deviceId}`)
+        const label = this.formatDeviceLabel(deviceId)
+        this.log.debug(`Device removed: ${label}`)
         this.removeStaleAccessories()
       })
 
       this.yotoAccount.on('online', ({ deviceId, metadata }) => {
+        const label = this.formatDeviceLabel(deviceId)
         const reason = metadata?.reason ? ` (${metadata.reason})` : ''
-        this.log.info(`Device online: ${deviceId}${reason}`)
+        this.log.info(`Device online: ${label}${reason}`)
       })
 
       this.yotoAccount.on('offline', ({ deviceId, metadata }) => {
+        const label = this.formatDeviceLabel(deviceId)
         const reason = metadata?.reason ? ` (${metadata.reason})` : ''
-        this.log.info(`Device offline: ${deviceId}${reason}`)
+        this.log.info(`Device offline: ${label}${reason}`)
       })
 
-      /**
-       * @param {string} deviceId
-       * @returns {string}
-       */
-      const getDeviceLabel = (deviceId) => {
-        const deviceName = this.yotoAccount?.getDevice(deviceId)?.device?.name
-        return deviceName || deviceId
-      }
-
       /**
        * @param {{ status?: Record<string, unknown> } | null | undefined} message
        * @returns {string}
@@ -212,79 +248,85 @@ export class YotoPlatform {
       }
 
       this.yotoAccount.on('statusUpdate', ({ deviceId, source, changedFields }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         const fields = Array.from(changedFields).join(', ')
         this.log.debug(`Status update [${label} ${source}]: ${fields}`)
       })
 
       this.yotoAccount.on('configUpdate', ({ deviceId, changedFields }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         const fields = Array.from(changedFields).join(', ')
         this.log.debug(`Config update [${label}]: ${fields}`)
       })
 
       this.yotoAccount.on('playbackUpdate', ({ deviceId, changedFields }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         const fields = Array.from(changedFields).join(', ')
         this.log.debug(`Playback update [${label}]: ${fields}`)
       })
 
       this.yotoAccount.on('mqttConnect', ({ deviceId }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT connected: ${label}`)
       })
 
       this.yotoAccount.on('mqttDisconnect', ({ deviceId, metadata }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         const reasonCode = metadata?.packet?.reasonCode
         const reason = typeof reasonCode === 'number' ? ` (code ${reasonCode})` : ''
         this.log.warn(`MQTT disconnected: ${label}${reason}`)
       })
 
       this.yotoAccount.on('mqttClose', ({ deviceId, metadata }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         const reason = metadata?.reason ? ` (${metadata.reason})` : ''
         this.log.debug(`MQTT closed: ${label}${reason}`)
       })
 
       this.yotoAccount.on('mqttReconnect', ({ deviceId }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT reconnecting: ${label}`)
       })
 
       this.yotoAccount.on('mqttOffline', ({ deviceId }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT offline: ${label}`)
       })
 
       this.yotoAccount.on('mqttEnd', ({ deviceId }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT ended: ${label}`)
       })
 
       this.yotoAccount.on('mqttStatus', ({ deviceId, topic }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT status [${label}]: ${topic}`)
       })
 
       this.yotoAccount.on('mqttEvents', ({ deviceId, topic }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT events [${label}]: ${topic}`)
       })
 
       this.yotoAccount.on('mqttStatusLegacy', ({ deviceId, topic, message }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         const fields = formatLegacyStatusFields(message)
         this.log.debug(`MQTT legacy status [${label}]: ${topic}${fields}`)
       })
 
-      this.yotoAccount.on('mqttResponse', ({ deviceId, topic }) => {
-        const label = getDeviceLabel(deviceId)
-        this.log.debug(`MQTT response [${label}]: ${topic}`)
+      this.yotoAccount.on('mqttResponse', ({ deviceId, topic, message }) => {
+        const label = this.formatDeviceLabel(deviceId)
+        let payload = ''
+        try {
+          payload = message ? ` ${JSON.stringify(message)}` : ''
+        } catch {
+          payload = ' [unserializable message]'
+        }
+        this.log.debug(`MQTT response [${label}]: ${topic}${payload}`)
       })
 
       this.yotoAccount.on('mqttUnknown', ({ deviceId, topic }) => {
-        const label = getDeviceLabel(deviceId)
+        const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT unknown [${label}]: ${topic}`)
       })
 
@@ -295,11 +337,59 @@ export class YotoPlatform {
 
       // Remove stale accessories after all devices are registered
       this.removeStaleAccessories()
+
+      await this.registerCardControlAccessories()
     } catch (error) {
       this.log.error('Failed to start account:', error instanceof Error ? error.message : String(error))
     }
   }
 
+  /**
+   * @param {string} deviceId
+   * @returns {string}
+   */
+  formatDeviceLabel (deviceId) {
+    const deviceName = this.yotoAccount?.getDevice(deviceId)?.device?.name
+    if (deviceName && deviceName !== deviceId) {
+      return `${deviceName} (${deviceId})`
+    }
+    return deviceId
+  }
+
+  /**
+   * @param {string} deviceId
+   * @returns {string}
+   */
+  getSpeakerAccessoryUuid (deviceId) {
+    return this.api.hap.uuid.generate(`${deviceId}:speaker`)
+  }
+
+  /**
+   * @param {YotoDevice} device
+   * @returns {string}
+   */
+  getSpeakerAccessoryName (device) {
+    const rawName = `${device.name} Speaker`
+    return sanitizeName(rawName) || `${device.deviceId} Speaker`
+  }
+
+  /**
+   * @param {CardControlConfig} control
+   * @returns {string}
+   */
+  getCardControlAccessoryUuid (control) {
+    return this.api.hap.uuid.generate(`card-control:${control.id}`)
+  }
+
+  /**
+   * @param {CardControlConfig} control
+   * @returns {string}
+   */
+  getCardControlAccessoryName (control) {
+    const rawName = `${control.label} (All Yotos)`
+    return sanitizeName(rawName) || `${control.cardId} (All Yotos)`
+  }
+
   /**
    * Register a device as a platform accessory
    * @param {YotoDevice} device - Device to register
@@ -338,6 +428,7 @@ export class YotoPlatform {
       // Update context with fresh device data
       existingAccessory.context = {
         ...existingAccessory.context,
+        type: 'device',
         device,
       }
 
@@ -362,6 +453,10 @@ export class YotoPlatform {
       // Initialize accessory (setup services and event listeners)
       await handler.setup()
 
+      if (this.playbackAccessoryConfig.mode === 'external') {
+        await this.registerSpeakerAccessory(device, deviceModel)
+      }
+
       return { success: true }
     } else {
       // Create new accessory
@@ -382,6 +477,7 @@ export class YotoPlatform {
 
       // Set accessory context
       accessory.context = {
+        type: 'device',
         device,
       }
 
@@ -402,6 +498,10 @@ export class YotoPlatform {
       this.log.debug(`Registering new accessory: ${device.name}`)
       this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory])
 
+      if (this.playbackAccessoryConfig.mode === 'external') {
+        await this.registerSpeakerAccessory(device, deviceModel)
+      }
+
       // Add to our tracking map (cast to typed version)
       this.accessories.set(uuid, accessory)
 
@@ -409,6 +509,169 @@ export class YotoPlatform {
     }
   }
 
+  /**
+   * Register a device as an external SmartSpeaker accessory
+   * @param {YotoDevice} device - Device to register
+   * @param {YotoDeviceModel} deviceModel - Device model instance
+   * @returns {Promise<{ success: boolean }>} Object indicating if registration succeeded
+   */
+  async registerSpeakerAccessory (device, deviceModel) {
+    const uuid = this.getSpeakerAccessoryUuid(device.deviceId)
+    const speakerName = this.getSpeakerAccessoryName(device)
+    if (this.speakerAccessories.has(uuid)) {
+      this.log.debug('SmartSpeaker accessory already published:', speakerName)
+      return { success: true }
+    }
+
+    this.log.info('Adding new SmartSpeaker accessory:', speakerName)
+
+    /** @type {PlatformAccessory<YotoAccessoryContext>} */
+    // eslint-disable-next-line new-cap
+    const accessory = new this.api.platformAccessory(
+      speakerName,
+      uuid,
+      this.api.hap.Categories.SPEAKER
+    )
+
+    const infoService = accessory.getService(this.api.hap.Service.AccessoryInformation)
+    if (infoService) {
+      infoService
+        .setCharacteristic(this.api.hap.Characteristic.Name, speakerName)
+        .setCharacteristic(this.api.hap.Characteristic.ConfiguredName, speakerName)
+    }
+
+    accessory.context = {
+      device,
+    }
+
+    const handler = new YotoSpeakerAccessory({
+      platform: this,
+      accessory,
+      deviceModel,
+    })
+
+    this.speakerAccessoryHandlers.set(uuid, handler)
+
+    await handler.setup()
+
+    this.log.info(`Publishing external SmartSpeaker accessory: ${speakerName}`)
+    this.api.publishExternalAccessories(PLUGIN_NAME, [accessory])
+
+    this.speakerAccessories.set(uuid, accessory)
+
+    return { success: true }
+  }
+
+  /**
+   * Register or update card control accessories that target all devices.
+   * @returns {Promise<void>}
+   */
+  async registerCardControlAccessories () {
+    const cardControls = getCardControlConfigs(this.config).filter(control => control.playOnAll)
+    const desiredUuids = new Set()
+
+    for (const control of cardControls) {
+      const uuid = this.getCardControlAccessoryUuid(control)
+      const accessoryName = this.getCardControlAccessoryName(control)
+      desiredUuids.add(uuid)
+
+      const existingAccessory = this.cardAccessories.get(uuid)
+      if (existingAccessory) {
+        this.log.debug('Restoring existing card control accessory from cache:', accessoryName)
+
+        if (existingAccessory.displayName !== accessoryName) {
+          existingAccessory.updateDisplayName(accessoryName)
+          const infoService = existingAccessory.getService(this.api.hap.Service.AccessoryInformation)
+          if (infoService) {
+            infoService
+              .setCharacteristic(this.api.hap.Characteristic.Name, accessoryName)
+              .setCharacteristic(this.api.hap.Characteristic.ConfiguredName, accessoryName)
+          }
+        }
+
+        existingAccessory.context = {
+          type: 'card-control',
+          cardControl: control,
+        }
+
+        this.api.updatePlatformAccessories([existingAccessory])
+
+        const existingHandler = this.cardAccessoryHandlers.get(uuid)
+        if (existingHandler) {
+          await existingHandler.stop().catch(error => {
+            this.log.error(`Failed to stop card control handler for ${existingAccessory.displayName}:`, error)
+          })
+          this.cardAccessoryHandlers.delete(uuid)
+        }
+
+        const handler = new YotoCardControlAccessory({
+          platform: this,
+          accessory: existingAccessory,
+          cardControl: control,
+        })
+
+        this.cardAccessoryHandlers.set(uuid, handler)
+        await handler.setup()
+        continue
+      }
+
+      this.log.debug('Adding new card control accessory:', accessoryName)
+
+      /** @type {PlatformAccessory<YotoCardAccessoryContext>} */
+      // eslint-disable-next-line new-cap
+      const accessory = new this.api.platformAccessory(
+        accessoryName,
+        uuid,
+        this.api.hap.Categories.SWITCH
+      )
+
+      const infoService = accessory.getService(this.api.hap.Service.AccessoryInformation)
+      if (infoService) {
+        infoService
+          .setCharacteristic(this.api.hap.Characteristic.Name, accessoryName)
+          .setCharacteristic(this.api.hap.Characteristic.ConfiguredName, accessoryName)
+      }
+
+      accessory.context = {
+        type: 'card-control',
+        cardControl: control,
+      }
+
+      const handler = new YotoCardControlAccessory({
+        platform: this,
+        accessory,
+        cardControl: control,
+      })
+
+      this.cardAccessoryHandlers.set(uuid, handler)
+      await handler.setup()
+
+      this.log.debug(`Registering card control accessory: ${accessoryName}`)
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory])
+
+      this.cardAccessories.set(uuid, accessory)
+    }
+
+    for (const [uuid, accessory] of this.cardAccessories) {
+      if (desiredUuids.has(uuid)) {
+        continue
+      }
+
+      this.log.debug('Removing card control accessory from cache:', accessory.displayName)
+
+      const handler = this.cardAccessoryHandlers.get(uuid)
+      if (handler) {
+        await handler.stop().catch(error => {
+          this.log.error(`Failed to stop card control handler for ${accessory.displayName}:`, error)
+        })
+        this.cardAccessoryHandlers.delete(uuid)
+      }
+
+      this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory])
+      this.cardAccessories.delete(uuid)
+    }
+  }
+
   /**
    * Remove accessories that are no longer present in the account
    */
@@ -441,6 +704,23 @@ export class YotoPlatform {
         this.accessories.delete(uuid)
       }
     }
+
+    for (const [uuid, accessory] of this.speakerAccessories) {
+      const deviceId = accessory.context.device?.deviceId
+      if (!deviceId || !currentDeviceIds.includes(deviceId)) {
+        this.log.debug('Removing external SmartSpeaker accessory from runtime:', accessory.displayName)
+
+        const handler = this.speakerAccessoryHandlers.get(uuid)
+        if (handler) {
+          handler.stop().catch(error => {
+            this.log.error(`Failed to stop SmartSpeaker handler for ${accessory.displayName}:`, error)
+          })
+          this.speakerAccessoryHandlers.delete(uuid)
+        }
+
+        this.speakerAccessories.delete(uuid)
+      }
+    }
   }
 
   /**
@@ -458,10 +738,28 @@ export class YotoPlatform {
         })
       )
     }
+    for (const [uuid, handler] of this.speakerAccessoryHandlers) {
+      stopPromises.push(
+        handler.stop().catch(error => {
+          this.log.error(`Failed to stop SmartSpeaker handler for ${uuid}:`, error)
+        })
+      )
+    }
+    for (const [uuid, handler] of this.cardAccessoryHandlers) {
+      stopPromises.push(
+        handler.stop().catch(error => {
+          this.log.error(`Failed to stop card control handler for ${uuid}:`, error)
+        })
+      )
+    }
 
     // Wait for all handlers to cleanup
     await Promise.all(stopPromises)
     this.accessoryHandlers.clear()
+    this.speakerAccessoryHandlers.clear()
+    this.cardAccessoryHandlers.clear()
+    this.speakerAccessories.clear()
+    this.cardAccessories.clear()
 
     // Stop the YotoAccount (disconnects all device models and MQTT)
     if (this.yotoAccount) {

package/lib/service-config.js

@@ -0,0 +1,63 @@
+/** @import { PlatformConfig } from 'homebridge' */
+
+/**
+ * @typedef {'bridged' | 'external' | 'none'} PlaybackAccessoryMode
+ */
+
+/**
+ * @typedef {Object} PlaybackAccessoryConfig
+ * @property {PlaybackAccessoryMode} mode
+ * @property {boolean} playbackEnabled
+ * @property {boolean} volumeEnabled
+ * @property {boolean} isLegacy
+ */
+
+const PLAYBACK_ACCESSORY_MODES = new Set(['bridged', 'external', 'none'])
+
+/**
+ * @param {unknown} value
+ * @param {boolean} fallback
+ * @returns {boolean}
+ */
+function getBooleanSetting (value, fallback) {
+  return typeof value === 'boolean' ? value : fallback
+}
+
+/**
+ * @param {unknown} value
+ * @param {PlaybackAccessoryMode} fallback
+ * @returns {PlaybackAccessoryMode}
+ */
+function parsePlaybackAccessoryMode (value, fallback) {
+  if (typeof value === 'string' && PLAYBACK_ACCESSORY_MODES.has(value)) {
+    return /** @type {PlaybackAccessoryMode} */ (value)
+  }
+  return fallback
+}
+
+/**
+ * @param {PlatformConfig} config
+ * @returns {PlaybackAccessoryConfig}
+ */
+export function getPlaybackAccessoryConfig (config) {
+  const services = config && typeof config === 'object' ? config['services'] : undefined
+  const serviceConfig = typeof services === 'object' && services !== null
+    ? /** @type {Record<string, unknown>} */ (services)
+    : {}
+
+  const hasPlaybackAccessory = Object.prototype.hasOwnProperty.call(serviceConfig, 'playbackAccessory')
+  const legacyPlayback = getBooleanSetting(serviceConfig['playback'], true)
+  const legacyVolume = getBooleanSetting(serviceConfig['volume'], true)
+
+  const legacyMode = legacyPlayback || legacyVolume ? 'bridged' : 'none'
+  const mode = hasPlaybackAccessory
+    ? parsePlaybackAccessoryMode(serviceConfig['playbackAccessory'], 'bridged')
+    : legacyMode
+
+  return {
+    mode,
+    playbackEnabled: hasPlaybackAccessory ? mode === 'bridged' : legacyPlayback,
+    volumeEnabled: hasPlaybackAccessory ? mode === 'bridged' : legacyVolume,
+    isLegacy: !hasPlaybackAccessory,
+  }
+}