homebridge-yoto 0.0.1 → 0.0.3

package/lib/auth.js

@@ -0,0 +1,220 @@
+/**
+ * @fileoverview OAuth2 Device Authorization Flow implementation for Yoto API
+ */
+
+/** @import { Logger } from 'homebridge' */
+/** @import { YotoApiTokenResponse, YotoApiDeviceCodeResponse } from './types.js' */
+
+import {
+  YOTO_OAUTH_DEVICE_CODE_URL,
+  YOTO_OAUTH_TOKEN_URL,
+  OAUTH_CLIENT_ID,
+  OAUTH_AUDIENCE,
+  OAUTH_SCOPE,
+  OAUTH_POLLING_INTERVAL,
+  OAUTH_DEVICE_CODE_TIMEOUT,
+  ERROR_MESSAGES,
+  LOG_PREFIX
+} from './constants.js'
+
+/**
+ * OAuth2 authentication handler for Yoto API
+ */
+export class YotoAuth {
+  /**
+   * @param {Logger} log - Homebridge logger
+   * @param {string} [clientId] - OAuth client ID (uses default if not provided)
+   */
+  constructor (log, clientId) {
+    this.log = log
+    this.clientId = clientId || OAUTH_CLIENT_ID
+  }
+
+  /**
+   * Initiate device authorization flow
+   * @returns {Promise<YotoApiDeviceCodeResponse>}
+   */
+  async initiateDeviceFlow () {
+    this.log.info(LOG_PREFIX.AUTH, 'Initiating device authorization flow...')
+
+    try {
+      const response = await fetch(YOTO_OAUTH_DEVICE_CODE_URL, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          client_id: this.clientId,
+          scope: OAUTH_SCOPE,
+          audience: OAUTH_AUDIENCE
+        })
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        throw new Error(`Device code request failed: ${response.status} ${errorText}`)
+      }
+
+      const data = /** @type {YotoApiDeviceCodeResponse} */ (await response.json())
+
+      this.log.info(LOG_PREFIX.AUTH, '='.repeat(60))
+      this.log.info(LOG_PREFIX.AUTH, 'YOTO AUTHENTICATION REQUIRED')
+      this.log.info(LOG_PREFIX.AUTH, '='.repeat(60))
+      this.log.info(LOG_PREFIX.AUTH, '')
+      this.log.info(LOG_PREFIX.AUTH, `1. Visit: ${data.verification_uri}`)
+      this.log.info(LOG_PREFIX.AUTH, `2. Enter code: ${data.user_code}`)
+      this.log.info(LOG_PREFIX.AUTH, '')
+      this.log.info(LOG_PREFIX.AUTH, `Or visit: ${data.verification_uri_complete}`)
+      this.log.info(LOG_PREFIX.AUTH, '')
+      this.log.info(LOG_PREFIX.AUTH, `Code expires in ${Math.floor(data.expires_in / 60)} minutes`)
+      this.log.info(LOG_PREFIX.AUTH, '='.repeat(60))
+
+      return data
+    } catch (error) {
+      this.log.error(LOG_PREFIX.AUTH, 'Failed to initiate device flow:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Poll for authorization completion
+   * @param {string} deviceCode - Device code from initiation
+   * @returns {Promise<YotoApiTokenResponse>}
+   */
+  async pollForAuthorization (deviceCode) {
+    const startTime = Date.now()
+    const timeout = OAUTH_DEVICE_CODE_TIMEOUT
+
+    this.log.info(LOG_PREFIX.AUTH, 'Waiting for user authorization...')
+
+    while (Date.now() - startTime < timeout) {
+      try {
+        const response = await fetch(YOTO_OAUTH_TOKEN_URL, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json'
+          },
+          body: JSON.stringify({
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            device_code: deviceCode,
+            client_id: this.clientId
+          })
+        })
+
+        if (response.ok) {
+          const tokenData = /** @type {YotoApiTokenResponse} */ (await response.json())
+          this.log.info(LOG_PREFIX.AUTH, '✓ Authorization successful!')
+          return tokenData
+        }
+
+        const errorData = /** @type {any} */ (await response.json().catch(() => ({})))
+
+        // Handle specific OAuth errors
+        if (errorData.error === 'authorization_pending') {
+          // Still waiting for user to authorize
+          await this.sleep(OAUTH_POLLING_INTERVAL)
+          continue
+        }
+
+        if (errorData.error === 'slow_down') {
+          // Server wants us to slow down polling
+          await this.sleep(OAUTH_POLLING_INTERVAL * 2)
+          continue
+        }
+
+        if (errorData.error === 'expired_token') {
+          throw new Error('Device code expired. Please restart the authorization process.')
+        }
+
+        if (errorData.error === 'access_denied') {
+          throw new Error('Authorization was denied by the user.')
+        }
+
+        // Unknown error
+        throw new Error(`Authorization failed: ${errorData.error || response.statusText}`)
+      } catch (error) {
+        if (error instanceof Error && error.message.includes('expired')) {
+          throw error
+        }
+        this.log.debug(LOG_PREFIX.AUTH, 'Polling error:', error)
+        await this.sleep(OAUTH_POLLING_INTERVAL)
+      }
+    }
+
+    throw new Error('Authorization timed out. Please try again.')
+  }
+
+  /**
+   * Refresh access token using refresh token
+   * @param {string} refreshToken - Refresh token
+   * @returns {Promise<YotoApiTokenResponse>}
+   */
+  async refreshAccessToken (refreshToken) {
+    this.log.debug(LOG_PREFIX.AUTH, 'Refreshing access token...')
+
+    try {
+      const response = await fetch(YOTO_OAUTH_TOKEN_URL, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          grant_type: 'refresh_token',
+          refresh_token: refreshToken,
+          client_id: this.clientId
+        })
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        throw new Error(`Token refresh failed: ${response.status} ${errorText}`)
+      }
+
+      const tokenData = /** @type {YotoApiTokenResponse} */ (await response.json())
+      this.log.info(LOG_PREFIX.AUTH, '✓ Token refreshed successfully')
+      return tokenData
+    } catch (error) {
+      this.log.error(LOG_PREFIX.AUTH, ERROR_MESSAGES.TOKEN_REFRESH_FAILED, error)
+      throw error
+    }
+  }
+
+  /**
+   * Complete device authorization flow
+   * @returns {Promise<YotoApiTokenResponse>}
+   */
+  async authorize () {
+    const deviceCodeResponse = await this.initiateDeviceFlow()
+    const tokenResponse = await this.pollForAuthorization(deviceCodeResponse.device_code)
+    return tokenResponse
+  }
+
+  /**
+   * Check if token is expired or expiring soon
+   * @param {number} expiresAt - Token expiration timestamp (seconds since epoch)
+   * @param {number} bufferSeconds - Seconds before expiry to consider expired
+   * @returns {boolean}
+   */
+  isTokenExpired (expiresAt, bufferSeconds = 300) {
+    const now = Math.floor(Date.now() / 1000)
+    return expiresAt <= now + bufferSeconds
+  }
+
+  /**
+   * Calculate token expiration timestamp
+   * @param {number} expiresIn - Seconds until token expires
+   * @returns {number} - Unix timestamp when token expires
+   */
+  calculateExpiresAt (expiresIn) {
+    return Math.floor(Date.now() / 1000) + expiresIn
+  }
+
+  /**
+   * Sleep for specified milliseconds
+   * @param {number} ms - Milliseconds to sleep
+   * @returns {Promise<void>}
+   */
+  sleep (ms) {
+    return new Promise(resolve => setTimeout(resolve, ms))
+  }
+}

package/lib/constants.js

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Constants and default values for the Yoto Homebridge plugin
+ */
+
+/**
+ * Plugin identification constants
+ */
+export const PLATFORM_NAME = 'Yoto'
+export const PLUGIN_NAME = 'homebridge-yoto'
+
+/**
+ * Yoto API endpoints
+ */
+export const YOTO_API_BASE_URL = 'https://api.yotoplay.com'
+export const YOTO_OAUTH_AUTHORIZE_URL = `${YOTO_API_BASE_URL}/authorize`
+export const YOTO_OAUTH_TOKEN_URL = `${YOTO_API_BASE_URL}/oauth/token`
+export const YOTO_OAUTH_DEVICE_CODE_URL = `${YOTO_API_BASE_URL}/oauth/device/code`
+
+/**
+ * MQTT configuration
+ */
+export const YOTO_MQTT_BROKER_URL = 'mqtt://mqtt.yotoplay.com:1883'
+export const MQTT_RECONNECT_PERIOD = 5000 // milliseconds
+export const MQTT_CONNECT_TIMEOUT = 30000 // milliseconds
+
+/**
+ * MQTT topic templates
+ */
+export const MQTT_TOPIC_DATA_STATUS = '/device/{deviceId}/data/status'
+export const MQTT_TOPIC_DATA_EVENTS = '/device/{deviceId}/data/events'
+export const MQTT_TOPIC_RESPONSE = '/device/{deviceId}/response'
+export const MQTT_TOPIC_COMMAND_STATUS_REQUEST = '/device/{deviceId}/command/status/request'
+export const MQTT_TOPIC_COMMAND_EVENTS_REQUEST = '/device/{deviceId}/command/events/request'
+export const MQTT_TOPIC_COMMAND_VOLUME_SET = '/device/{deviceId}/command/volume/set'
+export const MQTT_TOPIC_COMMAND_CARD_START = '/device/{deviceId}/command/card/start'
+export const MQTT_TOPIC_COMMAND_CARD_STOP = '/device/{deviceId}/command/card/stop'
+export const MQTT_TOPIC_COMMAND_CARD_PAUSE = '/device/{deviceId}/command/card/pause'
+export const MQTT_TOPIC_COMMAND_CARD_RESUME = '/device/{deviceId}/command/card/resume'
+export const MQTT_TOPIC_COMMAND_SLEEP_TIMER = '/device/{deviceId}/command/sleep-timer/set'
+export const MQTT_TOPIC_COMMAND_AMBIENTS_SET = '/device/{deviceId}/command/ambients/set'
+export const MQTT_TOPIC_COMMAND_REBOOT = '/device/{deviceId}/command/reboot'
+
+/**
+ * OAuth configuration
+ */
+export const OAUTH_CLIENT_ID = 'Y4HJ8BFqRQ24GQoLzgOzZ2KSqWmFG8LI'
+export const OAUTH_AUDIENCE = 'https://api.yotoplay.com'
+export const OAUTH_SCOPE = 'profile offline_access openid'
+export const OAUTH_POLLING_INTERVAL = 5000 // milliseconds
+export const OAUTH_DEVICE_CODE_TIMEOUT = 300000 // 5 minutes
+
+/**
+ * Device polling and timeouts
+ */
+export const DEFAULT_STATUS_TIMEOUT_SECONDS = 120 // Mark device offline after no updates
+export const TOKEN_REFRESH_BUFFER_SECONDS = 300 // Refresh token 5 minutes before expiry
+export const INITIAL_STATUS_REQUEST_DELAY = 2000 // milliseconds after MQTT connect
+
+/**
+ * HomeKit service configuration
+ */
+export const DEFAULT_MANUFACTURER = 'Yoto'
+export const DEFAULT_MODEL = 'Yoto Player'
+export const LOW_BATTERY_THRESHOLD = 20 // percentage
+
+/**
+ * Volume configuration
+ */
+export const MIN_VOLUME = 0
+export const MAX_VOLUME = 100
+export const YOTO_MAX_VOLUME_LIMIT = 16 // Yoto's internal max volume scale
+
+/**
+ * Playback status mapping
+ */
+export const PLAYBACK_STATUS = {
+  PLAYING: 'playing',
+  PAUSED: 'paused',
+  STOPPED: 'stopped'
+}
+
+/**
+ * Card insertion states
+ */
+export const CARD_INSERTION_STATE = {
+  NONE: 0,
+  PHYSICAL: 1,
+  REMOTE: 2
+}
+
+/**
+ * Day mode states
+ */
+export const DAY_MODE = {
+  UNKNOWN: -1,
+  NIGHT: 0,
+  DAY: 1
+}
+
+/**
+ * Power source states
+ */
+export const POWER_SOURCE = {
+  BATTERY: 0,
+  V2_DOCK: 1,
+  USB_C: 2,
+  QI_DOCK: 3
+}
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG = {
+  platform: PLATFORM_NAME,
+  name: PLATFORM_NAME,
+  clientId: OAUTH_CLIENT_ID,
+  mqttBroker: YOTO_MQTT_BROKER_URL,
+  statusTimeoutSeconds: DEFAULT_STATUS_TIMEOUT_SECONDS,
+  exposeTemperature: true,
+  exposeBattery: true,
+  exposeAdvancedControls: false,
+  exposeConnectionStatus: true,
+  exposeCardDetection: false,
+  exposeDisplayBrightness: true,
+  exposeSleepTimer: false,
+  exposeVolumeLimits: false,
+  exposeAmbientLight: false,
+  exposeActiveContent: true,
+  updateAccessoryName: false,
+  volumeControlType: 'speaker',
+  debug: false
+}
+
+/**
+ * Error messages
+ */
+export const ERROR_MESSAGES = {
+  NO_AUTH: 'No authentication credentials found. Please complete OAuth setup.',
+  TOKEN_EXPIRED: 'Access token expired. Attempting to refresh...',
+  TOKEN_REFRESH_FAILED: 'Failed to refresh access token. Please re-authenticate.',
+  MQTT_CONNECTION_FAILED: 'Failed to connect to MQTT broker.',
+  MQTT_DISCONNECTED: 'MQTT connection lost. Attempting to reconnect...',
+  DEVICE_OFFLINE: 'Device appears to be offline.',
+  API_ERROR: 'API request failed',
+  INVALID_CONFIG: 'Invalid configuration'
+}
+
+/**
+ * Log prefixes
+ */
+export const LOG_PREFIX = {
+  AUTH: '[Auth]',
+  API: '[API]',
+  MQTT: '[MQTT]',
+  PLATFORM: '[Platform]',
+  ACCESSORY: '[Accessory]'
+}

package/lib/platform.js

@@ -0,0 +1,269 @@
+/**
+ * @fileoverview Main platform implementation for Yoto Homebridge plugin
+ */
+
+/** @import { API, DynamicPlatformPlugin, Logger, PlatformAccessory, PlatformConfig } from 'homebridge' */
+/** @import { YotoDevice, YotoPlatformConfig, YotoAccessoryContext } from './types.js' */
+
+import { YotoAuth } from './auth.js'
+import { YotoApi } from './yotoApi.js'
+import { YotoMqtt } from './yotoMqtt.js'
+import { YotoPlayerAccessory } from './playerAccessory.js'
+import {
+  PLATFORM_NAME,
+  PLUGIN_NAME,
+  DEFAULT_CONFIG,
+  ERROR_MESSAGES,
+  LOG_PREFIX
+} from './constants.js'
+
+/**
+ * Yoto Platform implementation
+ * @implements {DynamicPlatformPlugin}
+ */
+export class YotoPlatform {
+  /**
+   * @param {Logger} log - Homebridge logger
+   * @param {PlatformConfig & YotoPlatformConfig} config - Platform configuration
+   * @param {API} api - Homebridge API
+   */
+  constructor (log, config, api) {
+    this.log = log
+    this.config = /** @type {YotoPlatformConfig} */ ({ ...DEFAULT_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 = []
+
+    // Initialize API clients
+    this.auth = new YotoAuth(log, this.config.clientId)
+    this.yotoApi = new YotoApi(log, this.auth)
+    this.yotoMqtt = new YotoMqtt(log, {
+      brokerUrl: this.config.mqttBroker
+    })
+
+    // Set up token refresh callback
+    this.yotoApi.setTokenRefreshCallback(this.handleTokenRefresh.bind(this))
+
+    this.log.debug(LOG_PREFIX.PLATFORM, 'Initializing platform:', this.config.name)
+
+    // 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)
+      })
+    })
+  }
+
+  /**
+   * Initialize the platform - authenticate and discover devices
+   * @returns {Promise<void>}
+   */
+  async initialize () {
+    try {
+      // Check if we have stored credentials
+      if (!this.config.accessToken || !this.config.refreshToken) {
+        this.log.warn(LOG_PREFIX.PLATFORM, ERROR_MESSAGES.NO_AUTH)
+        this.log.info(LOG_PREFIX.PLATFORM, 'Starting OAuth flow...')
+
+        const tokenResponse = await this.auth.authorize()
+
+        // 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.log.info(LOG_PREFIX.PLATFORM, '✓ Authentication successful!')
+        this.log.warn(LOG_PREFIX.PLATFORM, 'IMPORTANT: Please update your Homebridge config with the following:')
+        this.log.warn(LOG_PREFIX.PLATFORM, JSON.stringify({
+          accessToken: this.config.accessToken,
+          refreshToken: this.config.refreshToken,
+          tokenExpiresAt: this.config.tokenExpiresAt
+        }, null, 2))
+      }
+
+      // Set tokens in API client
+      this.yotoApi.setTokens(
+        this.config.accessToken || '',
+        this.config.refreshToken || '',
+        this.config.tokenExpiresAt || 0
+      )
+
+      // Connect to MQTT
+      await this.yotoMqtt.connect(this.config.accessToken)
+
+      // Discover and register devices
+      await this.discoverDevices()
+    } catch (error) {
+      this.log.error(LOG_PREFIX.PLATFORM, 'Initialization failed:', error)
+    }
+  }
+
+  /**
+   * 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.info(LOG_PREFIX.PLATFORM, 'Token refreshed, please update your config')
+    this.config.accessToken = accessToken
+    this.config.refreshToken = refreshToken
+    this.config.tokenExpiresAt = expiresAt
+
+    // Update MQTT connection with new token
+    this.yotoMqtt.disconnect().then(() => {
+      return this.yotoMqtt.connect(accessToken)
+    }).catch(error => {
+      this.log.error(LOG_PREFIX.PLATFORM, 'Failed to reconnect MQTT after token refresh:', error)
+    })
+  }
+
+  /**
+   * 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.info(LOG_PREFIX.PLATFORM, 'Loading accessory from cache:', accessory.displayName)
+
+    // Add to our tracking map
+    this.accessories.set(accessory.UUID, accessory)
+  }
+
+  /**
+   * Discover Yoto devices and register as accessories
+   * @returns {Promise<void>}
+   */
+  async discoverDevices () {
+    try {
+      this.log.info(LOG_PREFIX.PLATFORM, 'Discovering Yoto devices...')
+
+      // Fetch devices from API
+      const devices = await this.yotoApi.getDevices()
+
+      if (devices.length === 0) {
+        this.log.warn(LOG_PREFIX.PLATFORM, 'No Yoto devices found in account')
+        return
+      }
+
+      // Process each device
+      for (const device of devices) {
+        await this.registerDevice(device)
+      }
+
+      // Remove accessories that are no longer present
+      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
+    }
+  }
+
+  /**
+   * Register a device as a platform accessory
+   * @param {YotoDevice} device - Device to register
+   * @returns {Promise<void>}
+   */
+  async registerDevice (device) {
+    // Generate UUID for this device
+    const uuid = this.api.hap.uuid.generate(device.deviceId)
+    this.discoveredUUIDs.push(uuid)
+
+    // Check if accessory already exists
+    const existingAccessory = this.accessories.get(uuid)
+
+    if (existingAccessory) {
+      // Accessory exists - update it
+      this.log.info(LOG_PREFIX.PLATFORM, 'Restoring existing accessory:', device.name)
+
+      // Update context with fresh device data
+      const typedAccessory = /** @type {PlatformAccessory<YotoAccessoryContext>} */ (existingAccessory)
+      typedAccessory.context.device = device
+      typedAccessory.context.lastUpdate = Date.now()
+
+      // Update accessory information
+      this.api.updatePlatformAccessories([existingAccessory])
+
+      // Create handler for this accessory
+      // eslint-disable-next-line no-new
+      new YotoPlayerAccessory(this, typedAccessory)
+    } else {
+      // Create new accessory
+      this.log.info(LOG_PREFIX.PLATFORM, 'Adding new accessory:', device.name)
+
+      // Create platform accessory
+      // eslint-disable-next-line new-cap
+      const accessory = new this.api.platformAccessory(device.name, uuid)
+
+      // Create typed accessory with context
+      const typedAccessory = /** @type {PlatformAccessory<YotoAccessoryContext>} */ (accessory)
+
+      // Set accessory context
+      typedAccessory.context = {
+        device,
+        lastStatus: null,
+        lastEvents: null,
+        lastUpdate: Date.now()
+      }
+
+      // Create handler for this accessory
+      // eslint-disable-next-line no-new
+      new YotoPlayerAccessory(this, typedAccessory)
+
+      // Register with Homebridge
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory])
+
+      // Add to our tracking map
+      this.accessories.set(uuid, typedAccessory)
+    }
+  }
+
+  /**
+   * 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.info(LOG_PREFIX.PLATFORM, 'Removing stale accessory:', accessory.displayName)
+        staleAccessories.push(accessory)
+      }
+    }
+
+    if (staleAccessories.length > 0) {
+      this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, staleAccessories)
+
+      // Remove from tracking map
+      for (const accessory of staleAccessories) {
+        this.accessories.delete(accessory.UUID)
+      }
+    }
+  }
+
+  /**
+   * Shutdown handler - cleanup connections
+   */
+  async shutdown () {
+    this.log.info(LOG_PREFIX.PLATFORM, 'Shutting down...')
+
+    try {
+      await this.yotoMqtt.disconnect()
+    } catch (error) {
+      this.log.error(LOG_PREFIX.PLATFORM, 'Error during shutdown:', error)
+    }
+  }
+}