homebridge-yoto 0.0.27 → 0.0.31

package/lib/platform.js

@@ -2,464 +2,372 @@
  * @fileoverview Main platform implementation for Yoto Homebridge plugin
  */
 
-/** @import { API, DynamicPlatformPlugin, Logger, PlatformAccessory, PlatformConfig } from 'homebridge' */
-/** @import { YotoDevice, YotoPlatformConfig, YotoAccessoryContext } from './types.js' */
-
-import { readFile, writeFile, mkdir } from 'fs/promises'
-import { join } from 'path'
-import { YotoAuth } from './auth.js'
-import { YotoApi } from './yotoApi.js'
-import { YotoPlayerAccessory } from './playerAccessory.js'
+/** @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' */
+
+/**
+ * Context stored in PlatformAccessory for Yoto devices
+ * @typedef {Object} YotoAccessoryContext
+ * @property {YotoDevice} device - Device metadata from Yoto API
+ */
+
+import { readFile, writeFile } from 'node:fs/promises'
+import { YotoAccount } from 'yoto-nodejs-client'
+import { randomUUID } from 'node:crypto'
 import {
   PLATFORM_NAME,
   PLUGIN_NAME,
-  DEFAULT_CONFIG,
-  ERROR_MESSAGES,
-  LOG_PREFIX
-} from './constants.js'
+  DEFAULT_CLIENT_ID,
+} from './settings.js'
+import { YotoPlayerAccessory } from './accessory.js'
+import { sanitizeName } from './sanitize-name.js'
 
 /**
  * Yoto Platform implementation
+ * This class is the main constructor for your plugin, this is where you should
+ * parse the user config and discover/register accessories with Homebridge.
  * @implements {DynamicPlatformPlugin}
  */
 export class YotoPlatform {
+  /** @type {Logger} */ log
+  /** @type {PlatformConfig} */ config
+  /** @type {API} */ api
+  /** @type {typeof Service} */ Service
+  /** @type {typeof Characteristic} */ Characteristic
+  /** @type {Map<string, PlatformAccessory<YotoAccessoryContext>>} */ accessories = new Map()
+  /** @type {Map<string, YotoPlayerAccessory>} */ accessoryHandlers = new Map()
+  /** @type {YotoAccount | null} */ yotoAccount = null
+  /** @type {string} */ sessionId = randomUUID()
+
   /**
    * @param {Logger} log - Homebridge logger
-   * @param {PlatformConfig & YotoPlatformConfig} config - Platform configuration
+   * @param {PlatformConfig} config - Platform configuration
    * @param {API} api - Homebridge API
    */
   constructor (log, config, api) {
     this.log = log
-    this.config = /** @type {YotoPlatformConfig} */ ({ ...DEFAULT_CONFIG, ...config })
+    this.config = config
     this.api = api
-
-    // Homebridge service and characteristic references
     this.Service = api.hap.Service
     this.Characteristic = api.hap.Characteristic
 
-    // Track registered accessories
-    /** @type {Map<string, PlatformAccessory<YotoAccessoryContext>>} */
-    this.accessories = new Map()
-
-    // Track discovered device UUIDs
-    /** @type {string[]} */
-    this.discoveredUUIDs = []
+    log.debug('Finished initializing platform:', config.name)
 
-    // Persistent storage path for tokens
-    this.storagePath = api.user.storagePath()
-    this.tokenFilePath = join(this.storagePath, 'homebridge-yoto-tokens.json')
+    // Extract auth tokens once
+    const clientId = config['clientId'] || DEFAULT_CLIENT_ID
+    const refreshToken = config['refreshToken']
+    const accessToken = config['accessToken']
 
-    // Track accessory handlers for status updates
-    /** @type {Map<string, import('./playerAccessory.js').YotoPlayerAccessory>} */
-    this.accessoryHandlers = new Map()
+    // Debug: Log what we found (redacted)
+    log.debug('Config check - Has refreshToken:', !!refreshToken)
+    log.debug('Config check - Has accessToken:', !!accessToken)
+    log.debug('Config check - ClientId:', clientId ? 'present' : 'missing')
 
-    // Status polling interval
-    this.statusPollInterval = null
-
-    // Cache of user's owned MYO card IDs
-    /** @type {Set<string>} */
-    this.ownedCardIds = new Set()
+    // Check if we have authentication tokens
+    if (!refreshToken || !accessToken) {
+      log.warn('No authentication tokens found. Please configure the plugin through the Homebridge UI.')
+      return
+    }
 
-    // Initialize API clients
-    this.auth = new YotoAuth(log, this.config.clientId)
-    this.yotoApi = new YotoApi(log, this.auth)
+    log.info('Authentication tokens found, initializing Yoto account...')
 
-    // Set up token refresh callback
-    this.yotoApi.setTokenRefreshCallback(this.handleTokenRefresh.bind(this))
+    const { updateHomebridgeConfig, sessionId } = this
 
-    this.log.debug(LOG_PREFIX.PLATFORM, 'Initializing platform:', this.config.name)
+    // Initialize YotoAccount with client and device options
+    this.yotoAccount = new YotoAccount({
+      clientOptions: {
+        clientId,
+        refreshToken,
+        accessToken,
+        onTokenRefresh: async ({ updatedAccessToken, updatedRefreshToken, updatedExpiresAt, prevAccessToken, prevRefreshToken }) => {
+          log.info('Access token refreshed, expires at:', new Date(updatedExpiresAt * 1000).toISOString())
 
-    // Wait for Homebridge to finish launching
-    this.api.on('didFinishLaunching', () => {
-      this.log.debug(LOG_PREFIX.PLATFORM, 'Executed didFinishLaunching callback')
-      this.initialize().catch(error => {
-        this.log.error(LOG_PREFIX.PLATFORM, 'Failed to initialize:', error)
-      })
-    })
-  }
+          // Update config file with new tokens (similar to homebridge-ring pattern)
+          await updateHomebridgeConfig((configContents) => {
+            let updatedConfig = configContents
 
-  /**
-   * Initialize the platform - authenticate and discover devices
-   * @returns {Promise<void>}
-   */
-  async initialize () {
-    try {
-      // Load tokens from persistent storage
-      await this.loadTokens()
+            // Replace old tokens with new tokens
+            if (prevAccessToken) {
+              updatedConfig = updatedConfig.replace(prevAccessToken, updatedAccessToken)
+            }
+            if (prevRefreshToken && updatedRefreshToken) {
+              updatedConfig = updatedConfig.replace(prevRefreshToken, updatedRefreshToken)
+            }
 
-      // Check if we have stored credentials
-      if (!this.config.accessToken || !this.config.refreshToken) {
-        await this.performDeviceFlow()
+            return updatedConfig
+          })
+        }
+      },
+      deviceOptions: {
+        httpPollIntervalMs: config['httpPollIntervalMs'] || 60000,
+        yotoDeviceMqttOptions: {
+          sessionId
+        }
       }
+    })
 
-      // Set tokens in API client
-      this.yotoApi.setTokens(
-        this.config.accessToken || '',
-        this.config.refreshToken || '',
-        this.config.tokenExpiresAt || 0
-      )
-
-      // Discover and register devices
-      try {
-        await this.discoverDevices()
-      } catch (error) {
-        // Check if this is an auth error that requires re-authentication
-        if (error instanceof Error && error.message.includes('TOKEN_REFRESH_FAILED')) {
-          this.log.warn(LOG_PREFIX.PLATFORM, 'Token refresh failed, clearing tokens and restarting auth flow...')
-          await this.clearTokensAndReauth()
-          return
-        }
-        throw error
+    // Listen to account-level events
+    this.yotoAccount.on('error', ({ error, context }) => {
+      if (context.deviceId) {
+        log.error(`Device error [${context.deviceId} ${context.operation} ${context.source}]:`, error.message)
+      } else {
+        log.error('Account error:', error.message)
       }
+    })
 
-      // Fetch user's owned cards for lookup optimization
-      await this.fetchOwnedCards()
+    // When this event is fired it means Homebridge has restored all cached accessories from disk.
+    // Dynamic Platform plugins should only register new accessories after this event was fired,
+    // in order to ensure they weren't added to homebridge already. This event can also be used
+    // to start discovery of new accessories.
+    api.on('didFinishLaunching', async () => {
+      log.debug('Executed didFinishLaunching callback')
+      // Start the YotoAccount which will discover and start all devices
+      await this.startAccount()
+    })
 
-      // Start platform-level status polling (every 60 seconds)
-      this.startStatusPolling()
-    } catch (error) {
-      this.log.error(LOG_PREFIX.PLATFORM, 'Initialization failed:', error)
-    }
+    // When homebridge shuts down, cleanup all handlers and MQTT connections
+    api.on('shutdown', () => {
+      log.debug('Homebridge shutting down, cleaning up accessories...')
+      this.shutdown()
+    })
   }
 
   /**
-   * Start periodic status polling for all devices
+   * This function is invoked when homebridge restores cached accessories from disk at startup.
+   * It should be used to set up event handlers for characteristics and update respective values.
+   * In practice, it never is. It simply collects previously created devices into an accessories map
+   * that is then used to setup devices after didFinishLaunching fires.
+   * @param {PlatformAccessory} accessory - Cached accessory
    */
-  startStatusPolling () {
-    // Poll every 60 seconds
-    this.statusPollInterval = setInterval(async () => {
-      try {
-        await this.checkAllDevicesStatus()
-      } catch (error) {
-        this.log.error(LOG_PREFIX.PLATFORM, 'Failed to check device status:', error)
-      }
-    }, 60000)
-  }
+  configureAccessory (accessory) {
+    const { log, accessories } = this
+    log.info('Loading accessory from cache:', accessory.displayName)
 
-  /**
-   * Stop status polling
-   */
-  stopStatusPolling () {
-    if (this.statusPollInterval) {
-      clearInterval(this.statusPollInterval)
-      this.statusPollInterval = null
-    }
+    // Add to our tracking map (cast to our typed version)
+    accessories.set(accessory.UUID, /** @type {PlatformAccessory<YotoAccessoryContext>} */ (accessory))
   }
 
   /**
-   * Check all devices' online status and notify accessories
-   * @returns {Promise<void>}
+   * Start YotoAccount - discovers devices and creates device models
    */
-  async checkAllDevicesStatus () {
-    try {
-      // Fetch fresh device list from API (single call for all devices)
-      const devices = await this.yotoApi.getDevices()
-
-      // Update each accessory with fresh device info
-      for (const device of devices) {
-        const uuid = this.api.hap.uuid.generate(device.deviceId)
-        const accessory = this.accessories.get(uuid)
-
-        if (accessory) {
-          const wasOnline = accessory.context.device.online
-          const isNowOnline = device.online
-
-          // Update device info in context
-          accessory.context.device = device
-
-          // Notify accessory handler if status changed
-          const handler = this.accessoryHandlers.get(uuid)
-          if (handler && wasOnline !== isNowOnline) {
-            handler.handleOnlineStatusChange(isNowOnline, wasOnline)
-          }
-        }
-      }
-    } catch (error) {
-      this.log.error(LOG_PREFIX.PLATFORM, 'Error checking device status:', error)
+  async startAccount () {
+    if (!this.yotoAccount) {
+      this.log.error('Cannot start account - YotoAccount not initialized')
+      return
     }
-  }
 
-  /**
-   * Fetch user's owned MYO cards and cache their IDs
-   * @returns {Promise<void>}
-   */
-  async fetchOwnedCards () {
     try {
-      this.log.debug(LOG_PREFIX.PLATFORM, 'Fetching user\'s owned cards...')
-      const myContent = await this.yotoApi.getMyContent()
-
-      // Cache card IDs
-      if (myContent.cards && Array.isArray(myContent.cards)) {
-        this.ownedCardIds.clear()
-        for (const card of myContent.cards) {
-          if (card.cardId) {
-            this.ownedCardIds.add(card.cardId)
-          }
-        }
-        this.log.info(LOG_PREFIX.PLATFORM, `✓ Cached ${this.ownedCardIds.size} owned card(s)`)
-      }
-    } catch (error) {
-      this.log.warn(LOG_PREFIX.PLATFORM, 'Failed to fetch owned cards, card details may be limited:', error)
-    }
-  }
+      this.log.info('Starting Yoto account...')
 
-  /**
-   * Check if a card is owned by the user
-   * @param {string} cardId - Card ID to check
-   * @returns {boolean}
-   */
-  isCardOwned (cardId) {
-    return this.ownedCardIds.has(cardId)
-  }
-
-  /**
-   * Handle token refresh - update config
-   * Perform device authorization flow
-   * @returns {Promise<void>}
-   */
-  async performDeviceFlow () {
-    this.log.warn(LOG_PREFIX.PLATFORM, ERROR_MESSAGES.NO_AUTH)
-    this.log.debug(LOG_PREFIX.PLATFORM, 'Starting OAuth flow...')
+      // Listen for devices being added
+      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}`)
+          return
+        }
 
-    const tokenResponse = await this.auth.authorize()
+        const device = deviceModel.device
+        this.log.info(`Device discovered: ${device.name} (${deviceId})`)
+        await this.registerDevice(device, deviceModel)
+      })
 
-    // Store tokens in config
-    this.config.accessToken = tokenResponse.access_token
-    this.config.refreshToken = tokenResponse.refresh_token || ''
-    this.config.tokenExpiresAt = this.auth.calculateExpiresAt(tokenResponse.expires_in)
+      this.yotoAccount.on('deviceRemoved', ({ deviceId }) => {
+        this.log.info(`Device removed: ${deviceId}`)
+        this.removeStaleAccessories()
+      })
 
-    // Save tokens to persistent storage
-    await this.saveTokens()
+      this.yotoAccount.on('online', ({ deviceId, metadata }) => {
+        const reason = metadata?.reason ? ` (${metadata.reason})` : ''
+        this.log.info(`Device online: ${deviceId}${reason}`)
+      })
 
-    this.log.info(LOG_PREFIX.PLATFORM, '✓ Authentication successful and saved!')
-  }
+      this.yotoAccount.on('offline', ({ deviceId, metadata }) => {
+        const reason = metadata?.reason ? ` (${metadata.reason})` : ''
+        this.log.info(`Device offline: ${deviceId}${reason}`)
+      })
 
-  /**
-   * Clear invalid tokens and restart authentication
-   * @returns {Promise<void>}
-   */
-  async clearTokensAndReauth () {
-    // Clear tokens from config
-    this.config.accessToken = ''
-    this.config.refreshToken = ''
-    this.config.tokenExpiresAt = 0
+      this.yotoAccount.on('statusUpdate', ({ deviceId, source, changedFields }) => {
+        const fields = Array.from(changedFields).join(', ')
+        this.log.debug(`Status update [${deviceId} ${source}]: ${fields}`)
+      })
 
-    // Save cleared tokens
-    await this.saveTokens()
+      this.yotoAccount.on('configUpdate', ({ deviceId, changedFields }) => {
+        const fields = Array.from(changedFields).join(', ')
+        this.log.debug(`Config update [${deviceId}]: ${fields}`)
+      })
 
-    // Restart initialization
-    await this.initialize()
-  }
+      this.yotoAccount.on('playbackUpdate', ({ deviceId, changedFields }) => {
+        const fields = Array.from(changedFields).join(', ')
+        this.log.debug(`Playback update [${deviceId}]: ${fields}`)
+      })
 
-  /**
-   * Handle token refresh - update config
-   * @param {string} accessToken - New access token
-   * @param {string} refreshToken - New refresh token
-   * @param {number} expiresAt - New expiration timestamp
-   */
-  handleTokenRefresh (accessToken, refreshToken, expiresAt) {
-    this.log.debug(LOG_PREFIX.PLATFORM, 'Token refreshed')
-    this.config.accessToken = accessToken
-    this.config.refreshToken = refreshToken
-    this.config.tokenExpiresAt = expiresAt
-
-    // Save updated tokens to persistent storage
-    this.saveTokens().catch(error => {
-      this.log.error(LOG_PREFIX.PLATFORM, 'Failed to save refreshed tokens:', error)
-    })
+      this.yotoAccount.on('mqttConnect', ({ deviceId }) => {
+        this.log.info(`MQTT connected: ${deviceId}`)
+      })
 
-    // Note: MQTT reconnection is handled by each accessory's own MQTT client
-  }
+      this.yotoAccount.on('mqttDisconnect', ({ deviceId, metadata }) => {
+        const reasonCode = metadata?.packet?.reasonCode
+        const reason = typeof reasonCode === 'number' ? ` (code ${reasonCode})` : ''
+        this.log.info(`MQTT disconnected: ${deviceId}${reason}`)
+      })
 
-  /**
-   * Load tokens from config or persistent storage
-   * Priority: config.json > persistent storage file
-   * @returns {Promise<void>}
-   */
-  async loadTokens () {
-    // First check if tokens are in config.json
-    if (this.config.accessToken && this.config.refreshToken) {
-      this.log.debug(LOG_PREFIX.PLATFORM, 'Using tokens from config.json')
-      return
-    }
+      this.yotoAccount.on('mqttClose', ({ deviceId, metadata }) => {
+        const reason = metadata?.reason ? ` (${metadata.reason})` : ''
+        this.log.debug(`MQTT closed: ${deviceId}${reason}`)
+      })
 
-    // Fall back to persistent storage file
-    try {
-      const data = await readFile(this.tokenFilePath, 'utf-8')
-      const tokens = JSON.parse(data)
-
-      if (tokens.accessToken && tokens.refreshToken) {
-        this.config.accessToken = tokens.accessToken
-        this.config.refreshToken = tokens.refreshToken
-        this.config.tokenExpiresAt = tokens.tokenExpiresAt
-        this.log.debug(LOG_PREFIX.PLATFORM, 'Loaded tokens from persistent storage')
-      }
-    } catch (error) {
-      // File doesn't exist or is invalid - not an error on first run
-      this.log.debug(LOG_PREFIX.PLATFORM, 'No saved tokens found in storage')
-    }
-  }
+      this.yotoAccount.on('mqttReconnect', ({ deviceId }) => {
+        this.log.debug(`MQTT reconnecting: ${deviceId}`)
+      })
 
-  /**
-   * Save tokens to persistent storage
-   * @returns {Promise<void>}
-   */
-  async saveTokens () {
-    try {
-      // Ensure storage directory exists
-      await mkdir(this.storagePath, { recursive: true })
+      this.yotoAccount.on('mqttOffline', ({ deviceId }) => {
+        this.log.debug(`MQTT offline: ${deviceId}`)
+      })
 
-      const tokens = {
-        accessToken: this.config.accessToken || '',
-        refreshToken: this.config.refreshToken || '',
-        tokenExpiresAt: this.config.tokenExpiresAt || 0
-      }
+      this.yotoAccount.on('mqttEnd', ({ deviceId }) => {
+        this.log.debug(`MQTT ended: ${deviceId}`)
+      })
 
-      await writeFile(this.tokenFilePath, JSON.stringify(tokens, null, 2), 'utf-8')
-      this.log.debug(LOG_PREFIX.PLATFORM, 'Saved tokens to persistent storage')
-    } catch (error) {
-      this.log.error(LOG_PREFIX.PLATFORM, 'Failed to save tokens:', error)
-      throw error
-    }
-  }
+      this.yotoAccount.on('mqttStatus', ({ deviceId, topic }) => {
+        this.log.debug(`MQTT status [${deviceId}]: ${topic}`)
+      })
 
-  /**
-   * Restore cached accessories from disk
-   * This is called by Homebridge on startup for each cached accessory
-   * @param {PlatformAccessory<YotoAccessoryContext>} accessory - Cached accessory
-   */
-  configureAccessory (accessory) {
-    this.log.debug(LOG_PREFIX.PLATFORM, 'Loading accessory from cache:', accessory.displayName)
+      this.yotoAccount.on('mqttEvents', ({ deviceId, topic }) => {
+        this.log.debug(`MQTT events [${deviceId}]: ${topic}`)
+      })
 
-    // Add to our tracking map
-    this.accessories.set(accessory.UUID, accessory)
-  }
+      this.yotoAccount.on('mqttStatusLegacy', ({ deviceId, topic }) => {
+        this.log.debug(`MQTT legacy status [${deviceId}]: ${topic}`)
+      })
 
-  /**
-   * Discover Yoto devices and register as accessories
-   * @returns {Promise<void>}
-   */
-  async discoverDevices () {
-    try {
-      this.log.debug(LOG_PREFIX.PLATFORM, 'Discovering Yoto devices...')
+      this.yotoAccount.on('mqttResponse', ({ deviceId, topic }) => {
+        this.log.debug(`MQTT response [${deviceId}]: ${topic}`)
+      })
 
-      // Fetch devices from API
-      const devices = await this.yotoApi.getDevices()
+      this.yotoAccount.on('mqttUnknown', ({ deviceId, topic }) => {
+        this.log.debug(`MQTT unknown [${deviceId}]: ${topic}`)
+      })
 
-      if (devices.length === 0) {
-        this.log.warn(LOG_PREFIX.PLATFORM, 'No Yoto devices found in account')
-        return
-      }
+      // Start the account (discovers devices, creates device models, starts MQTT)
+      await this.yotoAccount.start()
 
-      // Process each device
-      for (const device of devices) {
-        this.log.info(LOG_PREFIX.PLATFORM, 'Device from API:', JSON.stringify(device, null, 2))
-        await this.registerDevice(device)
-      }
+      this.log.info(`✓ Yoto account started with ${this.yotoAccount.devices.size} device(s)`)
 
-      // Remove accessories that are no longer present
+      // Remove stale accessories after all devices are registered
       this.removeStaleAccessories()
-
-      this.log.info(LOG_PREFIX.PLATFORM, `✓ Discovered ${devices.length} device(s)`)
     } catch (error) {
-      this.log.error(LOG_PREFIX.PLATFORM, 'Failed to discover devices:', error)
-      throw error
+      this.log.error('Failed to start account:', error instanceof Error ? error.message : String(error))
     }
   }
 
   /**
    * Register a device as a platform accessory
    * @param {YotoDevice} device - Device to register
-   * @returns {Promise<void>}
+   * @param {YotoDeviceModel} deviceModel - Device model instance
+   * @returns {Promise<{ success: boolean }>} Object indicating if registration succeeded
    */
-  async registerDevice (device) {
+  async registerDevice (device, deviceModel) {
     // Generate UUID for this device
     const uuid = this.api.hap.uuid.generate(device.deviceId)
-    this.discoveredUUIDs.push(uuid)
+    const sanitizedDeviceName = sanitizeName(device.name)
+    const accessoryCategory = this.api.hap.Categories.SPEAKER
 
     // Check if accessory already exists
     const existingAccessory = this.accessories.get(uuid)
 
     if (existingAccessory) {
       // Accessory exists - update it
-      // Use description (player name) for display
-      const displayName = device.description || device.name
-      this.log.debug(LOG_PREFIX.PLATFORM, 'Restoring existing accessory:', displayName)
+      this.log.info('Restoring existing accessory from cache:', device.name)
 
-      // Update display name and AccessoryInformation if it has changed
-      if (existingAccessory.displayName !== displayName) {
-        existingAccessory.displayName = displayName
+      // Update display name if it has changed
+      if (existingAccessory.displayName !== sanitizedDeviceName) {
+        existingAccessory.updateDisplayName(sanitizedDeviceName)
         const infoService = existingAccessory.getService(this.api.hap.Service.AccessoryInformation)
         if (infoService) {
+          // Only update Name, preserve user's ConfiguredName customization
+          // ConfiguredName is intentionally NOT updated here because:
+          // - It allows users to rename accessories in the Home app
+          // - Their custom names should survive Homebridge restarts and Yoto device name changes
+          // - Name stays in sync with Yoto's device name for plugin identification
           infoService
-            .setCharacteristic(this.api.hap.Characteristic.Name, displayName)
-            .setCharacteristic(this.api.hap.Characteristic.ConfiguredName, displayName)
+            .setCharacteristic(this.api.hap.Characteristic.Name, sanitizedDeviceName)
+            .setCharacteristic(this.api.hap.Characteristic.ConfiguredName, sanitizedDeviceName)
         }
       }
 
       // Update context with fresh device data
-      const typedAccessory = /** @type {PlatformAccessory<YotoAccessoryContext>} */ (existingAccessory)
-      typedAccessory.context.device = device
-      typedAccessory.context.lastUpdate = Date.now()
+      existingAccessory.context = {
+        ...existingAccessory.context,
+        device,
+      }
+
+      // Ensure category matches our current service model
+      if (existingAccessory.category !== accessoryCategory) {
+        existingAccessory.category = accessoryCategory
+      }
 
       // Update accessory information
       this.api.updatePlatformAccessories([existingAccessory])
 
-      // Create handler for this accessory
-      const handler = new YotoPlayerAccessory(this, typedAccessory)
+      // Create handler for this accessory with device model
+      const handler = new YotoPlayerAccessory({
+        platform: this,
+        accessory: existingAccessory,
+        deviceModel,
+      })
 
-      // Track handler for status updates
+      // Track handler
       this.accessoryHandlers.set(uuid, handler)
 
-      // Initialize accessory (connect MQTT, etc.)
-      handler.initialize().catch(error => {
-        this.log.error(LOG_PREFIX.PLATFORM, `Failed to initialize ${device.name}:`, error)
-      })
+      // Initialize accessory (setup services and event listeners)
+      await handler.setup()
+
+      return { success: true }
     } else {
       // Create new accessory
-      // Use description (player name) for display
-      const displayName = device.description || device.name
-      this.log.debug(LOG_PREFIX.PLATFORM, 'Adding new accessory:', displayName)
+      this.log.info('Adding new accessory:', device.name)
 
       // Create platform accessory
+      /** @type {PlatformAccessory<YotoAccessoryContext>} */
       // eslint-disable-next-line new-cap
-      const accessory = new this.api.platformAccessory(displayName, uuid)
+      const accessory = new this.api.platformAccessory(sanitizedDeviceName, uuid, accessoryCategory)
 
       // Set Name and ConfiguredName on AccessoryInformation service
       const infoService = accessory.getService(this.api.hap.Service.AccessoryInformation)
       if (infoService) {
         infoService
-          .setCharacteristic(this.api.hap.Characteristic.Name, displayName)
-          .setCharacteristic(this.api.hap.Characteristic.ConfiguredName, displayName)
+          .setCharacteristic(this.api.hap.Characteristic.Name, sanitizedDeviceName)
+          .setCharacteristic(this.api.hap.Characteristic.ConfiguredName, sanitizedDeviceName)
       }
 
-      // Create typed accessory with context
-      const typedAccessory = /** @type {PlatformAccessory<YotoAccessoryContext>} */ (accessory)
-
       // Set accessory context
-      typedAccessory.context = {
+      accessory.context = {
         device,
-        lastStatus: null,
-        lastEvents: null,
-        lastUpdate: Date.now()
       }
 
-      // Create handler for this accessory
-      const handler = new YotoPlayerAccessory(this, typedAccessory)
+      // Create handler for this accessory with device model
+      const handler = new YotoPlayerAccessory({
+        platform: this,
+        accessory,
+        deviceModel,
+      })
 
-      // Track handler for status updates
+      // Track handler
       this.accessoryHandlers.set(uuid, handler)
 
-      // Initialize accessory (connect MQTT, etc.)
-      handler.initialize().catch(error => {
-        this.log.error(LOG_PREFIX.PLATFORM, `Failed to initialize ${device.name}:`, error)
-      })
+      // Initialize accessory (setup services and event listeners)
+      await handler.setup()
 
-      // Register with Homebridge
+      // Register as a platform accessory (bridged).
+      this.log.info(`Registering new accessory: ${device.name}`)
       this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory])
 
-      // Add to our tracking map
-      this.accessories.set(uuid, typedAccessory)
+      // Add to our tracking map (cast to typed version)
+      this.accessories.set(uuid, accessory)
+
+      return { success: true }
     }
   }
 
@@ -467,48 +375,79 @@ export class YotoPlatform {
    * Remove accessories that are no longer present in the account
    */
   removeStaleAccessories () {
-    const staleAccessories = []
-
-    for (const [uuid, accessory] of this.accessories) {
-      if (!this.discoveredUUIDs.includes(uuid)) {
-        this.log.debug(LOG_PREFIX.PLATFORM, 'Removing stale accessory:', accessory.displayName)
-        staleAccessories.push(accessory)
-      }
+    if (!this.yotoAccount) {
+      return
     }
 
-    if (staleAccessories.length > 0) {
-      this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, staleAccessories)
+    // Get current device IDs from account
+    const currentDeviceIds = this.yotoAccount.getDeviceIds()
+    const currentUUIDs = currentDeviceIds.map(id => this.api.hap.uuid.generate(id))
+
+    for (const [uuid, accessory] of this.accessories) {
+      if (!currentUUIDs.includes(uuid)) {
+        this.log.info('Removing existing accessory from cache:', accessory.displayName)
 
-      // Remove from tracking map and handlers
-      for (const accessory of staleAccessories) {
-        const handler = this.accessoryHandlers.get(accessory.UUID)
+        // Stop handler if it exists
+        const handler = this.accessoryHandlers.get(uuid)
         if (handler) {
-          handler.destroy().catch(error => {
-            this.log.error(LOG_PREFIX.PLATFORM, 'Error destroying accessory handler:', error)
+          handler.stop().catch(error => {
+            this.log.error(`Failed to stop handler for ${accessory.displayName}:`, error)
           })
-          this.accessoryHandlers.delete(accessory.UUID)
+          this.accessoryHandlers.delete(uuid)
         }
-        this.accessories.delete(accessory.UUID)
+
+        // Unregister from Homebridge
+        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory])
+
+        // Remove from our tracking map
+        this.accessories.delete(uuid)
       }
     }
   }
 
   /**
-   * Shutdown handler - cleanup connections
+   * Shutdown platform - cleanup all handlers and stop account
    */
   async shutdown () {
-    this.log.debug(LOG_PREFIX.PLATFORM, 'Shutting down...')
+    this.log.info('Shutting down Yoto platform...')
+
+    // Stop all accessory handlers
+    const stopPromises = []
+    for (const [uuid, handler] of this.accessoryHandlers) {
+      stopPromises.push(
+        handler.stop().catch(error => {
+          this.log.error(`Failed to stop handler for ${uuid}:`, error)
+        })
+      )
+    }
 
-    // Stop status polling
-    this.stopStatusPolling()
+    // Wait for all handlers to cleanup
+    await Promise.all(stopPromises)
+    this.accessoryHandlers.clear()
 
-    // Cleanup all accessory handlers
-    for (const [, handler] of this.accessoryHandlers) {
-      try {
-        await handler.destroy()
-      } catch (error) {
-        this.log.error(LOG_PREFIX.PLATFORM, 'Error shutting down accessory:', error)
-      }
+    // Stop the YotoAccount (disconnects all device models and MQTT)
+    if (this.yotoAccount) {
+      await this.yotoAccount.stop()
+      this.yotoAccount = null
+    }
+
+    this.log.info('✓ Yoto platform shutdown complete')
+  }
+
+  /**
+   * Update Homebridge config.json file
+   * @param {(configContents: string) => string} updateFn - Function to update config contents
+   */
+  async updateHomebridgeConfig (updateFn) {
+    const configPath = this.api.user.configPath()
+
+    try {
+      const configContents = await readFile(configPath, 'utf8')
+      const updatedContents = updateFn(configContents)
+      await writeFile(configPath, updatedContents, 'utf8')
+      this.log.debug('Updated config.json with new tokens')
+    } catch (error) {
+      this.log.error('Failed to update config.json:', error)
     }
   }
 }