@mdjhnson/homebridge-yoto 0.1.3 → 0.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 <img src="https://github.com/homebridge/branding/raw/latest/logos/homebridge-wordmark-logo-vertical.png" width="150">
 
-<img src="./logo.png" width="150">
+<img src="https://raw.githubusercontent.com/mdjhnson/homebridge-yoto/master/logo.png" width="150">
 
 </p>
 
@@ -33,7 +33,7 @@ Search for `@mdjhnson/homebridge-yoto` in the Homebridge UI **Plugins** tab, or
 npm install -g @mdjhnson/homebridge-yoto
 ```
 
-Requires Node.js 22+ and Homebridge 1.8+ or 2.x.
+Requires Node.js 22, 24 or 26 and Homebridge 1.8+ or 2.x.
 
 ## Sign in
 
@@ -110,6 +110,11 @@ The TV accessory, and the legacy Smart Speaker below, are external accessories.
 
 - **Switching from `homebridge-yoto`:** uninstall the original plugin first. Both register the `Yoto` platform and would conflict. Your existing `Yoto` config block keeps working, but bridged accessories are re-created, so you'll need to re-add them to rooms and automations.
 - **Removed external accessories:** if you turn off the Smart Speaker or TV accessory, or a player leaves your account, remove the old accessory from the Home app by hand. Homebridge can't unpublish external accessories.
+- **Yoto unreachable at startup:** if the network or Yoto's API is down when Homebridge starts, the plugin keeps retrying, waiting longer each time (up to 10 minutes between tries). You don't need to restart Homebridge. If Yoto rejects the saved login, the log asks you to sign in again instead of retrying.
+
+## Privacy
+
+The plugin only connects to Yoto's API and MQTT service, using your own sign-in. It has no analytics or tracking. The only file it changes is Homebridge's `config.json`, to save refreshed sign-in tokens. It writes a temporary copy next to `config.json` first and renames it into place, so an interrupted save can't corrupt the file.
 
 ## Development
 

package/lib/accessory.js

@@ -50,7 +50,7 @@ import { getPlaybackAccessoryConfig } from './service-config.js'
 import { getCardControlConfigs } from './card-controls.js'
 import { getCardStartOptions, getShortcutEntries, getShortcutsSignature, toPlayableCard } from './shortcuts.js'
 import { formatError } from './utils/error-format.js'
-import { ListenerGroup } from './utils/listener-group.js'
+import { ListenerGroup, logListenerError } from './utils/listener-group.js'
 import { setDeviceVolume } from './utils/set-device-volume.js'
 import { getBooleanSetting } from './utils/get-boolean-setting.js'
 import {
@@ -118,7 +118,10 @@ export class YotoPlayerAccessory {
     this.#platform = platform
     this.#accessory = accessory
     this.#deviceModel = deviceModel
-    this.#listeners = new ListenerGroup(deviceModel)
+    this.#listeners = new ListenerGroup(
+      deviceModel,
+      logListenerError(platform.log, `${LOG_PREFIX.ACCESSORY} [${accessory.context.device.name}]`)
+    )
     this.#log = platform.log
 
     // Extract device info from context

package/lib/platform.js

@@ -5,6 +5,7 @@
 /** @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 { YotoAccountEventMap } from 'yoto-nodejs-client/lib/yoto-account.js' */
 /** @import { PlaybackAccessoryConfig } from './service-config.js' */
 /** @import { CardControlConfig } from './card-controls.js' */
 
@@ -29,6 +30,7 @@ import {
   PLATFORM_NAME,
   PLUGIN_NAME,
   DEFAULT_CLIENT_ID,
+  LOG_PREFIX,
 } from './settings.js'
 import { YotoPlayerAccessory } from './accessory.js'
 import { YotoSpeakerAccessory } from './speaker-accessory.js'
@@ -37,10 +39,28 @@ import { YotoCardControlAccessory } from './card-control-accessory.js'
 import { sanitizeName } from './utils/sanitize-name.js'
 import { getPlaybackAccessoryConfig } from './service-config.js'
 import { getCardControlConfigs } from './card-controls.js'
-import { formatError } from './utils/error-format.js'
+import { errorMessage, formatError, getStatusCode } from './utils/error-format.js'
+import { ListenerGroup, logListenerError } from './utils/listener-group.js'
 import { applyTokenUpdate } from './utils/token-config.js'
 import { tolerateMissingStatusScope } from './utils/status-scope-fallback.js'
 
+/** First retry delay when the Yoto API can't be reached at startup; doubles each attempt */
+const START_RETRY_BASE_MS = 30 * 1000
+/** Longest wait between startup retries */
+const START_RETRY_MAX_MS = 10 * 60 * 1000
+
+/**
+ * Whether a failed account start could succeed if tried again. Network errors
+ * and 5xx responses are transient; other 4xx responses won't change on retry.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isRetryableStartError (error) {
+  const statusCode = getStatusCode(error)
+  if (statusCode === undefined) return true
+  return statusCode >= 500 || statusCode === 408 || statusCode === 429
+}
+
 /**
  * Yoto Platform implementation
  * This class is the main constructor for your plugin, this is where you should
@@ -63,8 +83,13 @@ export class YotoPlatform {
   /** @type {Map<string, YotoTelevisionAccessory>} */ televisionAccessoryHandlers = new Map()
   /** @type {Map<string, YotoCardControlAccessory>} */ cardAccessoryHandlers = new Map()
   /** @type {YotoAccount | null} */ yotoAccount = null
+  /** @type {ListenerGroup<YotoAccountEventMap> | null} */ accountListeners = null
   /** @type {string} */ sessionId = randomUUID()
   /** @type {Map<string, Promise<string | null>>} */ cardTitleCache = new Map()
+  /** @type {boolean} */ authInvalid = false
+  /** @type {number} */ startRetryCount = 0
+  /** @type {ReturnType<typeof setTimeout> | null} */ startRetryTimer = null
+  /** @type {boolean} */ shuttingDown = false
 
   /**
    * @param {Logger} log - Homebridge logger
@@ -102,63 +127,83 @@ export class YotoPlatform {
     const { sessionId } = this
     const updateHomebridgeConfig = this.updateHomebridgeConfig.bind(this)
 
-    // Initialize YotoAccount with client and device options
-    this.yotoAccount = new YotoAccount({
-      clientOptions: {
-        clientId,
-        refreshToken,
-        accessToken,
-        onTokenRefresh: async ({ updatedAccessToken, updatedRefreshToken, updatedExpiresAt, prevAccessToken, prevRefreshToken }) => {
-          // Client reports expiry in seconds; config.json stores milliseconds (matches the UI)
-          const tokenExpiresAt = updatedExpiresAt * 1000
-          log.debug('Access token refreshed, expires at:', new Date(tokenExpiresAt).toISOString())
-
-          // Keep the in-memory config in sync so later reads see current tokens
-          config['accessToken'] = updatedAccessToken
-          config['refreshToken'] = updatedRefreshToken
-          config['tokenExpiresAt'] = tokenExpiresAt
-
-          await updateHomebridgeConfig((configContents) => applyTokenUpdate(configContents, {
-            platform: PLATFORM_NAME,
-            accessToken: updatedAccessToken,
-            refreshToken: updatedRefreshToken,
-            tokenExpiresAt,
-            prevAccessToken,
-            prevRefreshToken,
-          }))
-        },
-        onRefreshStart: () => {
-          log.debug('Refreshing Yoto access token...')
-        },
-        onRefreshError: (error) => {
-          log.warn('Yoto token refresh failed, will retry:', error.message)
-          log.debug('Token refresh error details:', formatError(error))
-        },
-        onInvalid: (error) => {
-          log.error(
-            'Yoto login has expired or been revoked. Open the plugin settings in the Homebridge UI and sign in again.',
-            error.message
-          )
+    // Initialize YotoAccount with client and device options. It decodes the saved
+    // access token, which throws if config.json holds a malformed one; Homebridge
+    // doesn't catch errors from platform constructors, so it would crash on every start.
+    /** @type {YotoAccount} */
+    let account
+    try {
+      account = new YotoAccount({
+        clientOptions: {
+          clientId,
+          refreshToken,
+          accessToken,
+          onTokenRefresh: async ({ updatedAccessToken, updatedRefreshToken, updatedExpiresAt, prevAccessToken, prevRefreshToken }) => {
+            // Client reports expiry in seconds; config.json stores milliseconds (matches the UI)
+            const tokenExpiresAt = updatedExpiresAt * 1000
+            log.debug('Access token refreshed, expires at:', new Date(tokenExpiresAt).toISOString())
+
+            // Keep the in-memory config in sync so later reads see current tokens
+            config['accessToken'] = updatedAccessToken
+            config['refreshToken'] = updatedRefreshToken
+            config['tokenExpiresAt'] = tokenExpiresAt
+
+            await updateHomebridgeConfig((configContents) => applyTokenUpdate(configContents, {
+              platform: PLATFORM_NAME,
+              accessToken: updatedAccessToken,
+              refreshToken: updatedRefreshToken,
+              tokenExpiresAt,
+              prevAccessToken,
+              prevRefreshToken,
+            }))
+          },
+          onRefreshStart: () => {
+            log.debug('Refreshing Yoto access token...')
+          },
+          onRefreshError: (error) => {
+            log.warn('Yoto token refresh failed, will retry:', error.message)
+            log.debug('Token refresh error details:', formatError(error))
+          },
+          onInvalid: (error) => {
+            this.authInvalid = true
+            log.error(
+              'Yoto login has expired or been revoked. Open the plugin settings in the Homebridge UI and sign in again.',
+              error.message
+            )
+          },
         },
-      },
-      deviceOptions: {
-        httpPollIntervalMs: Math.max(10000, Number(config['httpPollIntervalMs']) || 60000),
-        yotoDeviceMqttOptions: {
-          sessionId
+        deviceOptions: {
+          httpPollIntervalMs: Math.max(10000, Number(config['httpPollIntervalMs']) || 60000),
+          yotoDeviceMqttOptions: {
+            sessionId
+          }
         }
-      }
-    })
+      })
+    } catch (error) {
+      log.error(
+        'Could not load the saved Yoto login. Open the plugin settings in the Homebridge UI and sign in again.',
+        errorMessage(error)
+      )
+      return
+    }
+    this.yotoAccount = account
+    // The account re-emits device events from MQTT and timer callbacks, so a
+    // throwing listener would be an uncaught exception that stops Homebridge
+    this.accountListeners = new ListenerGroup(account, logListenerError(log, LOG_PREFIX.PLATFORM))
 
     // The status endpoint needs a scope the Yoto dashboard doesn't offer yet
     tolerateMissingStatusScope(this.yotoAccount.client, (message) => log.debug(message))
 
     // Listen to account-level events
-    this.yotoAccount.on('error', ({ error, context }) => {
+    this.accountListeners.on('error', ({ error, context }) => {
       const details = formatError(error)
       if (context.deviceId) {
         const label = this.formatDeviceLabel(context.deviceId)
         log.error(`Device error [${label} ${context.operation} ${context.source}]:`, details)
         log.debug('Device error context:', context)
+      } else if (context.operation === 'start') {
+        // connectAccount() logs the failure and schedules a retry
+        log.debug('Account start error:', details)
       } else {
         log.error('Account error:', details)
         log.debug('Account error context:', context)
@@ -178,7 +223,9 @@ export class YotoPlatform {
     // When homebridge shuts down, cleanup all handlers and MQTT connections
     api.on('shutdown', () => {
       log.debug('Homebridge shutting down, cleaning up accessories...')
-      this.shutdown()
+      this.shutdown().catch(error => {
+        log.error('Error while shutting down:', formatError(error))
+      })
     })
   }
 
@@ -215,7 +262,8 @@ export class YotoPlatform {
    * Start YotoAccount - discovers devices and creates device models
    */
   async startAccount () {
-    if (!this.yotoAccount) {
+    const listeners = this.accountListeners
+    if (!this.yotoAccount || !listeners) {
       this.log.error('Cannot start account - YotoAccount not initialized')
       return
     }
@@ -234,35 +282,40 @@ export class YotoPlatform {
       }
 
       // Listen for devices being added
-      this.yotoAccount.on('deviceAdded', async ({ deviceId }) => {
-        // Homebridge may shut down while the account is still starting
-        if (!this.yotoAccount) return
-        const deviceModel = this.yotoAccount.getDevice(deviceId)
-        if (!deviceModel) {
-          const label = this.formatDeviceLabel(deviceId)
-          this.log.warn(`Device added but no model found for ${label}`)
-          return
+      listeners.on('deviceAdded', async ({ deviceId }) => {
+        // The account doesn't await this listener, so errors must not escape it
+        try {
+          // Homebridge may shut down while the account is still starting
+          if (this.shuttingDown || !this.yotoAccount) return
+          const deviceModel = this.yotoAccount.getDevice(deviceId)
+          if (!deviceModel) {
+            const label = this.formatDeviceLabel(deviceId)
+            this.log.warn(`Device added but no model found for ${label}`)
+            return
+          }
+
+          const device = deviceModel.device
+          this.log.info(`Device discovered: ${device.name} (${deviceId})`)
+          this.log.debug('Registering device from account discovery:', device.name, deviceId)
+          await this.registerDevice(device, deviceModel)
+        } catch (error) {
+          this.log.error(`Failed to set up ${this.formatDeviceLabel(deviceId)}:`, formatError(error))
         }
-
-        const device = deviceModel.device
-        this.log.info(`Device discovered: ${device.name} (${deviceId})`)
-        this.log.debug('Registering device from account discovery:', device.name, deviceId)
-        await this.registerDevice(device, deviceModel)
       })
 
-      this.yotoAccount.on('deviceRemoved', ({ deviceId }) => {
+      listeners.on('deviceRemoved', ({ deviceId }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`Device removed: ${label}`)
         this.removeStaleAccessories()
       })
 
-      this.yotoAccount.on('online', ({ deviceId, metadata }) => {
+      listeners.on('online', ({ deviceId, metadata }) => {
         const label = this.formatDeviceLabel(deviceId)
         const reason = metadata?.reason ? ` (${metadata.reason})` : ''
         this.log.info(`Device online: ${label}${reason}`)
       })
 
-      this.yotoAccount.on('offline', ({ deviceId, metadata }) => {
+      listeners.on('offline', ({ deviceId, metadata }) => {
         const label = this.formatDeviceLabel(deviceId)
         const reason = metadata?.reason ? ` (${metadata.reason})` : ''
         this.log.info(`Device offline: ${label}${reason}`)
@@ -282,74 +335,74 @@ export class YotoPlatform {
         return ` fields: ${preview}${suffix}`
       }
 
-      this.yotoAccount.on('statusUpdate', ({ deviceId, source, changedFields }) => {
+      listeners.on('statusUpdate', ({ deviceId, source, changedFields }) => {
         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 }) => {
+      listeners.on('configUpdate', ({ deviceId, changedFields }) => {
         const label = this.formatDeviceLabel(deviceId)
         const fields = Array.from(changedFields).join(', ')
         this.log.debug(`Config update [${label}]: ${fields}`)
       })
 
-      this.yotoAccount.on('playbackUpdate', ({ deviceId, changedFields }) => {
+      listeners.on('playbackUpdate', ({ deviceId, changedFields }) => {
         const label = this.formatDeviceLabel(deviceId)
         const fields = Array.from(changedFields).join(', ')
         this.log.debug(`Playback update [${label}]: ${fields}`)
       })
 
-      this.yotoAccount.on('mqttConnect', ({ deviceId }) => {
+      listeners.on('mqttConnect', ({ deviceId }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT connected: ${label}`)
       })
 
-      this.yotoAccount.on('mqttDisconnect', ({ deviceId, metadata }) => {
+      listeners.on('mqttDisconnect', ({ deviceId, metadata }) => {
         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 }) => {
+      listeners.on('mqttClose', ({ deviceId, metadata }) => {
         const label = this.formatDeviceLabel(deviceId)
         const reason = metadata?.reason ? ` (${metadata.reason})` : ''
         this.log.debug(`MQTT closed: ${label}${reason}`)
       })
 
-      this.yotoAccount.on('mqttReconnect', ({ deviceId }) => {
+      listeners.on('mqttReconnect', ({ deviceId }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT reconnecting: ${label}`)
       })
 
-      this.yotoAccount.on('mqttOffline', ({ deviceId }) => {
+      listeners.on('mqttOffline', ({ deviceId }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT offline: ${label}`)
       })
 
-      this.yotoAccount.on('mqttEnd', ({ deviceId }) => {
+      listeners.on('mqttEnd', ({ deviceId }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT ended: ${label}`)
       })
 
-      this.yotoAccount.on('mqttStatus', ({ deviceId, topic }) => {
+      listeners.on('mqttStatus', ({ deviceId, topic }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT status [${label}]: ${topic}`)
       })
 
-      this.yotoAccount.on('mqttEvents', ({ deviceId, topic }) => {
+      listeners.on('mqttEvents', ({ deviceId, topic }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT events [${label}]: ${topic}`)
       })
 
-      this.yotoAccount.on('mqttStatusLegacy', ({ deviceId, topic, message }) => {
+      listeners.on('mqttStatusLegacy', ({ deviceId, topic, message }) => {
         const label = this.formatDeviceLabel(deviceId)
         const fields = formatLegacyStatusFields(message)
         this.log.debug(`MQTT legacy status [${label}]: ${topic}${fields}`)
       })
 
-      this.yotoAccount.on('mqttResponse', ({ deviceId, topic, message }) => {
+      listeners.on('mqttResponse', ({ deviceId, topic, message }) => {
         const label = this.formatDeviceLabel(deviceId)
         let payload = ''
         try {
@@ -360,32 +413,80 @@ export class YotoPlatform {
         this.log.debug(`MQTT response [${label}]: ${topic}${payload}`)
       })
 
-      this.yotoAccount.on('mqttUnknown', ({ deviceId, topic }) => {
+      listeners.on('mqttUnknown', ({ deviceId, topic }) => {
         const label = this.formatDeviceLabel(deviceId)
         this.log.debug(`MQTT unknown [${label}]: ${topic}`)
       })
 
-      // Start the account (discovers devices, creates device models, starts MQTT)
-      const account = this.yotoAccount
+      await this.connectAccount()
+    } catch (error) {
+      this.log.error('Failed to start account:', errorMessage(error))
+    }
+  }
+
+  /**
+   * Start the account (discovers devices, creates device models, starts MQTT).
+   * If the Yoto API can't be reached, e.g. because the network isn't up yet
+   * when Homebridge boots, retry with backoff instead of giving up. Errors that
+   * a retry won't fix (an invalid login, other 4xx responses) are logged once.
+   * @returns {Promise<void>}
+   */
+  async connectAccount () {
+    const account = this.yotoAccount
+    if (!account || this.shuttingDown) return
+
+    try {
       await account.start()
+    } catch (error) {
+      // Homebridge shut down while the account was starting
+      if (this.shuttingDown) return
+      if (this.authInvalid) {
+        this.log.error('Failed to start account:', errorMessage(error))
+        return
+      }
+      const statusCode = getStatusCode(error)
+      if (statusCode === 401 || statusCode === 403) {
+        this.log.error(
+          `Yoto rejected the saved login (HTTP ${statusCode}). Open the plugin settings in the Homebridge UI and sign in again.`,
+          formatError(error)
+        )
+        return
+      }
+      if (!isRetryableStartError(error)) {
+        this.log.error('Failed to start account:', formatError(error))
+        return
+      }
+      const delayMs = Math.min(START_RETRY_MAX_MS, START_RETRY_BASE_MS * 2 ** this.startRetryCount)
+      this.startRetryCount++
+      this.log.warn(`Could not connect to Yoto (${errorMessage(error)}). Retrying in ${Math.round(delayMs / 1000)} seconds.`)
+      this.startRetryTimer = setTimeout(() => {
+        this.startRetryTimer = null
+        this.connectAccount().catch(retryError => {
+          this.log.error('Failed to start account:', formatError(retryError))
+        })
+      }, delayMs)
+      return
+    }
 
-      // Homebridge shut down while the account was starting; shutdown() cleans up
-      if (this.yotoAccount !== account) return
+    // Homebridge shut down while the account was starting. shutdown()'s stop() ran
+    // before start() finished, so stop the device models and MQTT start() just opened.
+    if (this.shuttingDown) {
+      await account.stop()
+      return
+    }
 
-      this.log.info(`✓ Yoto account started with ${account.devices.size} device(s)`)
-      this.log.debug(
-        'Account devices:',
-        Array.from(account.devices.keys()).join(', ') || 'none'
-      )
+    this.startRetryCount = 0
+    this.log.info(`✓ Yoto account started with ${account.devices.size} device(s)`)
+    this.log.debug(
+      'Account devices:',
+      Array.from(account.devices.keys()).join(', ') || 'none'
+    )
 
-      // Remove stale accessories after all devices are registered
-      this.removeStaleAccessories()
+    // Remove stale accessories after all devices are registered
+    this.removeStaleAccessories()
 
-      this.log.debug('Registering card control accessories (playOnAll).')
-      await this.registerCardControlAccessories()
-    } catch (error) {
-      this.log.error('Failed to start account:', error instanceof Error ? error.message : String(error))
-    }
+    this.log.debug('Registering card control accessories (playOnAll).')
+    await this.registerCardControlAccessories()
   }
 
   /**
@@ -928,6 +1029,11 @@ export class YotoPlatform {
    */
   async shutdown () {
     this.log.debug('Shutting down Yoto platform...')
+    this.shuttingDown = true
+    if (this.startRetryTimer) {
+      clearTimeout(this.startRetryTimer)
+      this.startRetryTimer = null
+    }
     this.log.debug(
       'Handlers to stop:',
       `devices=${this.accessoryHandlers.size}`,
@@ -1004,7 +1110,13 @@ export class YotoPlatform {
       // Keep the original file mode, since config.json holds tokens.
       const { mode } = await stat(configPath)
       const tmpPath = `${configPath}.${process.pid}.tmp`
-      await writeFile(tmpPath, updatedContents, { encoding: 'utf8', mode: mode & 0o777 })
+      try {
+        await writeFile(tmpPath, updatedContents, { encoding: 'utf8', mode: mode & 0o777 })
+      } catch (writeError) {
+        // Don't leave a partial copy of the tokens next to config.json
+        await unlink(tmpPath).catch(() => {})
+        throw writeError
+      }
       try {
         await rename(tmpPath, configPath)
       } catch (renameError) {
@@ -1015,8 +1127,7 @@ export class YotoPlatform {
       }
       this.log.debug('Updated config.json with new tokens')
     } catch (error) {
-      const details = error instanceof Error ? error.message : String(error)
-      this.log.error(`Failed to update config.json at ${configPath}. Refreshed tokens may not persist:`, details)
+      this.log.error(`Failed to update config.json at ${configPath}. Refreshed tokens may not persist:`, errorMessage(error))
     }
   }
 }

package/lib/speaker-accessory.js

@@ -17,7 +17,7 @@ import {
 import { sanitizeName } from './utils/sanitize-name.js'
 import { syncServiceNames } from './sync-service-names.js'
 import { formatError } from './utils/error-format.js'
-import { ListenerGroup } from './utils/listener-group.js'
+import { ListenerGroup, logListenerError } from './utils/listener-group.js'
 import { setDeviceVolume } from './utils/set-device-volume.js'
 import {
   clampPercent,
@@ -51,7 +51,10 @@ export class YotoSpeakerAccessory {
     this.#platform = platform
     this.#accessory = accessory
     this.#deviceModel = deviceModel
-    this.#listeners = new ListenerGroup(deviceModel)
+    this.#listeners = new ListenerGroup(
+      deviceModel,
+      logListenerError(platform.log, `${LOG_PREFIX.ACCESSORY} [${accessory.context.device.name}]`)
+    )
     this.#log = platform.log
 
     this.#device = accessory.context.device

package/lib/television-accessory.js

@@ -26,7 +26,7 @@ import {
 import { sanitizeName } from './utils/sanitize-name.js'
 import { syncServiceNames } from './sync-service-names.js'
 import { formatError } from './utils/error-format.js'
-import { ListenerGroup } from './utils/listener-group.js'
+import { ListenerGroup, logListenerError } from './utils/listener-group.js'
 import { setDeviceVolume } from './utils/set-device-volume.js'
 import { getTrimmedString } from './utils/get-trimmed-string.js'
 import { getCardControlConfigs } from './card-controls.js'
@@ -79,7 +79,10 @@ export class YotoTelevisionAccessory {
     this.#platform = platform
     this.#accessory = accessory
     this.#deviceModel = deviceModel
-    this.#listeners = new ListenerGroup(deviceModel)
+    this.#listeners = new ListenerGroup(
+      deviceModel,
+      logListenerError(platform.log, `${LOG_PREFIX.ACCESSORY} [${accessory.context.device.name}]`)
+    )
     this.#log = platform.log
 
     this.#device = accessory.context.device

package/lib/utils/error-format.js

@@ -1,3 +1,26 @@
+/**
+ * A one-line description of an error for user-facing logs. Includes the HTTP
+ * status for Yoto API errors, whose message alone is always
+ * "Unexpected response status code".
+ * @param {unknown} error
+ * @returns {string}
+ */
+export function errorMessage (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  const statusCode = getStatusCode(error)
+  return statusCode === undefined ? message : `${message} (HTTP ${statusCode})`
+}
+
+/**
+ * The HTTP status of a Yoto API error, if the error has one.
+ * @param {unknown} error
+ * @returns {number | undefined}
+ */
+export function getStatusCode (error) {
+  if (!error || typeof error !== 'object' || !('statusCode' in error)) return undefined
+  return typeof error.statusCode === 'number' ? error.statusCode : undefined
+}
+
 /**
  * @param {unknown} error
  * @returns {string}

package/lib/utils/listener-group.js

@@ -1,4 +1,19 @@
 /** @import { EventEmitter } from 'node:events' */
+/** @import { Logger } from 'homebridge' */
+
+import { formatError } from './error-format.js'
+
+/**
+ * A `ListenerGroup` error callback that logs the failure.
+ * @param {Logger} log
+ * @param {string} label - Names the listener's owner, e.g. `[Accessory] [Kitchen Yoto]`
+ * @returns {(event: string, error: unknown) => void}
+ */
+export function logListenerError (log, label) {
+  return (event, error) => {
+    log.error(`${label} Failed to handle ${event} event:`, formatError(error))
+  }
+}
 
 /**
  * Tracks listeners registered on a shared emitter so they can be removed
@@ -11,24 +26,44 @@
  */
 export class ListenerGroup {
   /** @type {EventEmitter} */ #emitter
+  /** @type {((event: string, error: unknown) => void) | undefined} */ #onListenerError
   /** @type {Array<[string, Parameters<EventEmitter['on']>[1]]>} */ #entries = []
 
   /**
    * @param {EventEmitter<TEvents>} emitter
+   * @param {(event: string, error: unknown) => void} [onListenerError] - Called when a
+   *   listener throws or its returned promise rejects. The device model emits from inside
+   *   MQTT and timer callbacks, where an escaping error would be an uncaught exception
+   *   (or unhandled rejection) that stops Homebridge.
    */
-  constructor (emitter) {
+  constructor (emitter, onListenerError) {
     this.#emitter = /** @type {EventEmitter} */ (/** @type {unknown} */ (emitter))
+    this.#onListenerError = onListenerError
   }
 
   /**
    * @template {keyof TEvents & string} K
    * @param {K} event
-   * @param {(...args: TEvents[K]) => void} listener
+   * @param {(...args: TEvents[K]) => unknown} listener
    * @returns {this}
    */
   on (event, listener) {
-    this.#emitter.on(event, listener)
-    this.#entries.push([event, listener])
+    const onListenerError = this.#onListenerError
+    const registered = onListenerError
+      ? (/** @type {TEvents[K]} */ ...args) => {
+          try {
+            const result = listener(...args)
+            if (result instanceof Promise) {
+              result.catch(error => { onListenerError(event, error) })
+            }
+          } catch (error) {
+            onListenerError(event, error)
+          }
+        }
+      : listener
+    const untyped = /** @type {Parameters<EventEmitter['on']>[1]} */ (registered)
+    this.#emitter.on(event, untyped)
+    this.#entries.push([event, untyped])
     return this
   }
 

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@mdjhnson/homebridge-yoto",
+  "displayName": "Homebridge Yoto",
   "description": "Control your Yoto players through Apple HomeKit with real-time MQTT updates",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "author": "mdjhnson (https://github.com/mdjhnson)",
   "contributors": [
     "Bret Comnes <bcomnes@gmail.com> (https://bret.io)"
@@ -9,6 +10,10 @@
   "bugs": {
     "url": "https://github.com/mdjhnson/homebridge-yoto/issues"
   },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/mdjhnson"
+  },
   "dependencies": {
     "@homebridge/plugin-ui-utils": "^2.2.6",
     "color-convert": "3.1.3",
@@ -27,20 +32,24 @@
     "typescript": "~5.9.3"
   },
   "engines": {
-    "node": ">=22",
+    "node": "^22.12.0 || ^24.0.0 || ^26.0.0",
     "npm": ">=10",
     "homebridge": "^1.8.0 || ^2.0.0"
   },
   "homepage": "https://github.com/mdjhnson/homebridge-yoto",
   "keywords": [
     "homebridge-plugin",
-    "yoto"
+    "supports-hap",
+    "homebridge",
+    "homekit",
+    "yoto",
+    "yoto-player",
+    "yoto-mini"
   ],
   "license": "MIT",
   "type": "module",
   "module": "index.js",
   "main": "index.js",
-  "types": "index.d.ts",
   "files": [
     "index.js",
     "config.schema.json",