homebridge-yoto 0.0.1 → 0.0.3

package/lib/types.js

@@ -0,0 +1,233 @@
+/**
+ * @fileoverview Type definitions for Yoto API and Homebridge integration
+ */
+
+/**
+ * @typedef {Object} YotoDevice
+ * @property {string} deviceId - Unique identifier for the device
+ * @property {string} name - Device name
+ * @property {string} description - Device description
+ * @property {boolean} online - Whether device is currently online
+ * @property {string} releaseChannel - Release channel (e.g., "stable", "beta")
+ * @property {string} deviceType - Type of device (e.g., "player")
+ * @property {string} deviceFamily - Device family (e.g., "yoto")
+ * @property {string} deviceGroup - Device group classification
+ */
+
+/**
+ * @typedef {Object} YotoDeviceStatus
+ * @property {number} statusVersion - Status data version
+ * @property {string} fwVersion - Firmware version
+ * @property {string} productType - Product type identifier
+ * @property {number} batteryLevel - Battery level (0-100)
+ * @property {number} als - Ambient light sensor reading
+ * @property {number} freeDisk - Free disk space in bytes
+ * @property {number} shutdownTimeout - Auto-shutdown timeout in seconds
+ * @property {number} dbatTimeout - Display battery timeout
+ * @property {number} charging - Charging state (0=not charging, 1=charging)
+ * @property {string | null} activeCard - Currently active card ID or null
+ * @property {number} cardInserted - Card insertion state (0=none, 1=physical, 2=remote)
+ * @property {number} playingStatus - Playing status code
+ * @property {boolean} headphones - Whether headphones are connected
+ * @property {number} dnowBrightness - Current display brightness
+ * @property {number} dayBright - Day mode brightness setting
+ * @property {number} nightBright - Night mode brightness setting
+ * @property {boolean} bluetoothHp - Bluetooth headphones enabled
+ * @property {number} volume - System volume level
+ * @property {number} userVolume - User volume level (0-100)
+ * @property {'12' | '24'} timeFormat - Time format preference
+ * @property {string} nightlightMode - Nightlight mode setting
+ * @property {string} temp - Temperature reading
+ * @property {number} day - Day mode (0=night, 1=day, -1=unknown)
+ */
+
+/**
+ * @typedef {Object} YotoPlaybackEvents
+ * @property {string} repeatAll - Repeat all setting ("true" or "false")
+ * @property {string} streaming - Streaming active ("true" or "false")
+ * @property {string} volume - Current volume level
+ * @property {string} volumeMax - Maximum volume level
+ * @property {string} playbackWait - Playback wait state ("true" or "false")
+ * @property {string} sleepTimerActive - Sleep timer active ("true" or "false")
+ * @property {string} eventUtc - Event timestamp (Unix timestamp)
+ * @property {string} trackLength - Track duration in seconds
+ * @property {string} position - Current playback position in seconds
+ * @property {string} cardId - Active card ID
+ * @property {string} source - Playback source (e.g., "card", "remote", "MQTT")
+ * @property {string} cardUpdatedAt - Card last updated timestamp (ISO8601)
+ * @property {string} chapterTitle - Current chapter title
+ * @property {string} chapterKey - Current chapter key
+ * @property {string} trackTitle - Current track title
+ * @property {string} trackKey - Current track key
+ * @property {string} playbackStatus - Playback status ("playing", "paused", "stopped")
+ * @property {string} sleepTimerSeconds - Sleep timer remaining seconds
+ */
+
+/**
+ * @typedef {Object} YotoDeviceConfigSettings
+ * @property {any[]} alarms - Alarm configurations
+ * @property {string} ambientColour - Ambient LED color (hex format)
+ * @property {string} bluetoothEnabled - Bluetooth enabled state
+ * @property {boolean} btHeadphonesEnabled - Bluetooth headphones enabled
+ * @property {string} clockFace - Clock face style
+ * @property {string} dayDisplayBrightness - Day display brightness
+ * @property {string} dayTime - Day mode start time
+ * @property {string} dayYotoDaily - Day mode Yoto Daily content
+ * @property {string} dayYotoRadio - Day mode Yoto Radio content
+ * @property {string} displayDimBrightness - Display dim brightness level
+ * @property {string} displayDimTimeout - Display dim timeout in seconds
+ * @property {boolean} headphonesVolumeLimited - Headphones volume limited
+ * @property {string} hourFormat - Hour format ("12" or "24")
+ * @property {string} locale - Locale setting
+ * @property {string} maxVolumeLimit - Max volume limit (0-16)
+ * @property {string} nightAmbientColour - Night ambient LED color
+ * @property {string} nightDisplayBrightness - Night display brightness
+ * @property {string} nightMaxVolumeLimit - Night max volume limit (0-16)
+ * @property {string} nightTime - Night mode start time
+ * @property {string} nightYotoDaily - Night mode Yoto Daily content
+ * @property {string} nightYotoRadio - Night mode Yoto Radio content
+ * @property {boolean} repeatAll - Repeat all tracks enabled
+ * @property {string} shutdownTimeout - Auto-shutdown timeout in seconds
+ * @property {string} volumeLevel - Volume level preset
+ */
+
+/**
+ * @typedef {Object} YotoDeviceConfig
+ * @property {string} name - Device name
+ * @property {YotoDeviceConfigSettings} config - Device configuration settings
+ */
+
+/**
+ * @typedef {Object} YotoCardContent
+ * @property {Object} [card] - Card information
+ * @property {string} [card.cardId] - Card unique identifier
+ * @property {string} [card.title] - Card title
+ * @property {string} [card.slug] - Card slug
+ * @property {string} [card.userId] - Owner user ID
+ * @property {string} [card.createdAt] - Creation timestamp
+ * @property {string} [card.updatedAt] - Update timestamp
+ * @property {boolean} [card.deleted] - Whether card is deleted
+ * @property {Object} [card.metadata] - Additional metadata
+ * @property {string} [card.metadata.author] - Card author
+ * @property {string} [card.metadata.category] - Content category
+ * @property {string} [card.metadata.description] - Card description
+ * @property {Object} [card.metadata.cover] - Cover image data
+ * @property {string} [card.metadata.cover.imageL] - Large cover image URL
+ * @property {Object} [card.metadata.media] - Media information
+ * @property {number} [card.metadata.media.duration] - Total duration in seconds
+ * @property {number} [card.metadata.media.fileSize] - File size in bytes
+ * @property {YotoChapter[]} [card.chapters] - Card chapters
+ */
+
+/**
+ * @typedef {Object} YotoChapter
+ * @property {string} key - Chapter key
+ * @property {string} title - Chapter title
+ * @property {string | null} availableFrom - Availability date (ISO8601)
+ * @property {YotoTrack[]} tracks - Chapter tracks
+ */
+
+/**
+ * @typedef {Object} YotoTrack
+ * @property {string} key - Track key
+ * @property {string} title - Track title
+ * @property {number} duration - Track duration in seconds
+ */
+
+/**
+ * @typedef {Object} YotoApiDevicesResponse
+ * @property {YotoDevice[]} devices - Array of devices
+ */
+
+/**
+ * @typedef {Object} YotoApiTokenResponse
+ * @property {string} access_token - Access token
+ * @property {string} token_type - Token type (typically "Bearer")
+ * @property {number} expires_in - Token lifetime in seconds
+ * @property {string} [refresh_token] - Refresh token
+ * @property {string} [scope] - Granted scopes
+ * @property {string} [id_token] - ID token JWT
+ */
+
+/**
+ * @typedef {Object} YotoApiDeviceCodeResponse
+ * @property {string} device_code - Device verification code
+ * @property {string} user_code - User-facing code to enter
+ * @property {string} verification_uri - URL for user to visit
+ * @property {string} verification_uri_complete - Complete verification URL with code
+ * @property {number} expires_in - Code lifetime in seconds
+ * @property {number} interval - Minimum polling interval in seconds
+ */
+
+/**
+ * @typedef {Object} YotoAccessoryContext
+ * @property {YotoDevice} device - Device information
+ * @property {YotoDeviceStatus | null} lastStatus - Last known device status
+ * @property {YotoPlaybackEvents | null} lastEvents - Last known playback events
+ * @property {number} lastUpdate - Timestamp of last update
+ * @property {YotoCardContent | null} [activeContentInfo] - Current active content information
+ */
+
+/**
+ * @typedef {Object} YotoPlatformConfig
+ * @property {string} [platform] - Platform name (should be "Yoto")
+ * @property {string} [name] - Platform instance name
+ * @property {string} [clientId] - OAuth client ID
+ * @property {string} [accessToken] - Stored access token
+ * @property {string} [refreshToken] - Stored refresh token
+ * @property {number} [tokenExpiresAt] - Token expiration timestamp
+ * @property {string} [mqttBroker] - MQTT broker URL
+ * @property {number} [statusTimeoutSeconds] - Seconds before marking device offline
+ * @property {boolean} [exposeTemperature] - Expose temperature sensor
+ * @property {boolean} [exposeBattery] - Expose battery service
+ * @property {boolean} [exposeAdvancedControls] - Expose advanced control switches
+ * @property {boolean} [exposeConnectionStatus] - Expose connection status sensor
+ * @property {boolean} [exposeCardDetection] - Expose card detection sensor
+ * @property {boolean} [exposeDisplayBrightness] - Expose display brightness control
+ * @property {boolean} [exposeSleepTimer] - Expose sleep timer control
+ * @property {boolean} [exposeVolumeLimits] - Expose volume limit controls
+ * @property {boolean} [exposeAmbientLight] - Expose ambient light color control
+ * @property {boolean} [exposeActiveContent] - Track and display active content information
+ * @property {boolean} [updateAccessoryName] - Update accessory display name with current content
+ * @property {string} [volumeControlType] - Volume control service type
+ * @property {boolean} [debug] - Enable debug logging
+ */
+
+/**
+ * @typedef {Object} MqttCommandResponse
+ * @property {Object} status - Response status
+ * @property {string} req_body - Stringified request body
+ */
+
+/**
+ * MQTT command payloads
+ */
+
+/**
+ * @typedef {Object} MqttVolumeCommand
+ * @property {number} volume - Volume level (0-100)
+ */
+
+/**
+ * @typedef {Object} MqttAmbientCommand
+ * @property {number} r - Red intensity (0-255)
+ * @property {number} g - Green intensity (0-255)
+ * @property {number} b - Blue intensity (0-255)
+ */
+
+/**
+ * @typedef {Object} MqttSleepTimerCommand
+ * @property {number} seconds - Sleep timer duration (0 to disable)
+ */
+
+/**
+ * @typedef {Object} MqttCardStartCommand
+ * @property {string} uri - Card URI (e.g., "https://yoto.io/{cardId}")
+ * @property {string} [chapterKey] - Chapter to start from
+ * @property {string} [trackKey] - Track to start from
+ * @property {number} [secondsIn] - Playback start offset in seconds
+ * @property {number} [cutOff] - Playback stop offset in seconds
+ * @property {boolean} [anyButtonStop] - Whether any button stops playback
+ */
+
+export {}

package/lib/yotoApi.js

@@ -0,0 +1,260 @@
+/**
+ * @fileoverview REST API client for Yoto API
+ */
+
+/** @import { Logger } from 'homebridge' */
+/** @import { YotoApiDevicesResponse, YotoDevice, YotoDeviceConfig, YotoCardContent } from './types.js' */
+/** @import { YotoAuth } from './auth.js' */
+
+import {
+  YOTO_API_BASE_URL,
+  ERROR_MESSAGES,
+  LOG_PREFIX
+} from './constants.js'
+
+/**
+ * Yoto REST API client
+ */
+export class YotoApi {
+  /**
+   * @param {Logger} log - Homebridge logger
+   * @param {YotoAuth} auth - Authentication handler
+   */
+  constructor (log, auth) {
+    this.log = log
+    this.auth = auth
+    this.accessToken = null
+    this.refreshToken = null
+    this.tokenExpiresAt = 0
+  }
+
+  /**
+   * Set authentication tokens
+   * @param {string} accessToken - Access token
+   * @param {string} refreshToken - Refresh token
+   * @param {number} expiresAt - Token expiration timestamp
+   */
+  setTokens (accessToken, refreshToken, expiresAt) {
+    this.accessToken = accessToken
+    this.refreshToken = refreshToken
+    this.tokenExpiresAt = expiresAt
+  }
+
+  /**
+   * Check if we have valid authentication
+   * @returns {boolean}
+   */
+  hasAuth () {
+    return !!this.accessToken
+  }
+
+  /**
+   * Ensure we have a valid access token, refreshing if necessary
+   * @returns {Promise<void>}
+   */
+  async ensureValidToken () {
+    if (!this.accessToken) {
+      throw new Error(ERROR_MESSAGES.NO_AUTH)
+    }
+
+    // Check if token needs refresh
+    if (this.auth.isTokenExpired(this.tokenExpiresAt)) {
+      this.log.info(LOG_PREFIX.API, ERROR_MESSAGES.TOKEN_EXPIRED)
+
+      if (!this.refreshToken) {
+        throw new Error(ERROR_MESSAGES.TOKEN_REFRESH_FAILED)
+      }
+
+      try {
+        const tokenResponse = await this.auth.refreshAccessToken(this.refreshToken)
+        this.accessToken = tokenResponse.access_token
+        this.tokenExpiresAt = this.auth.calculateExpiresAt(tokenResponse.expires_in)
+
+        // Update refresh token if a new one was provided
+        if (tokenResponse.refresh_token) {
+          this.refreshToken = tokenResponse.refresh_token
+        }
+
+        // Notify platform to save updated tokens
+        if (this.onTokenRefreshCallback) {
+          this.onTokenRefreshCallback(this.accessToken, this.refreshToken, this.tokenExpiresAt)
+        }
+      } catch (error) {
+        this.log.error(LOG_PREFIX.API, 'Token refresh failed:', error)
+        throw error
+      }
+    }
+  }
+
+  /**
+   * Make an authenticated API request
+   * @param {string} endpoint - API endpoint path
+   * @param {RequestInit & { _retried?: boolean }} [options] - Fetch options
+   * @returns {Promise<any>}
+   */
+  async request (endpoint, options = {}) {
+    await this.ensureValidToken()
+
+    const url = `${YOTO_API_BASE_URL}${endpoint}`
+
+    const headers = {
+      Authorization: `Bearer ${this.accessToken}`,
+      'Content-Type': 'application/json',
+      ...options.headers
+    }
+
+    try {
+      this.log.debug(LOG_PREFIX.API, `${options.method || 'GET'} ${endpoint}`)
+
+      const response = await fetch(url, {
+        ...options,
+        headers
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        this.log.error(LOG_PREFIX.API, `Request failed: ${response.status} ${errorText}`)
+
+        // Handle 401 by attempting token refresh once
+        if (response.status === 401 && !options._retried) {
+          this.log.warn(LOG_PREFIX.API, 'Received 401, forcing token refresh...')
+          this.tokenExpiresAt = 0 // Force refresh
+          await this.ensureValidToken()
+          return this.request(endpoint, { ...options, _retried: true })
+        }
+
+        throw new Error(`API request failed: ${response.status} ${errorText}`)
+      }
+
+      // Return empty object for 204 No Content
+      if (response.status === 204) {
+        return {}
+      }
+
+      return await response.json()
+    } catch (error) {
+      this.log.error(LOG_PREFIX.API, `${ERROR_MESSAGES.API_ERROR}:`, error)
+      throw error
+    }
+  }
+
+  /**
+   * Get all devices associated with the authenticated user
+   * @returns {Promise<YotoDevice[]>}
+   */
+  async getDevices () {
+    this.log.debug(LOG_PREFIX.API, 'Fetching devices...')
+
+    const response = /** @type {YotoApiDevicesResponse} */ (await this.request('/device-v2/devices/mine'))
+
+    this.log.info(LOG_PREFIX.API, `Found ${response.devices.length} device(s)`)
+    return response.devices
+  }
+
+  /**
+   * Get device configuration
+   * @param {string} deviceId - Device ID
+   * @returns {Promise<YotoDeviceConfig>}
+   */
+  async getDeviceConfig (deviceId) {
+    this.log.debug(LOG_PREFIX.API, `Fetching config for device ${deviceId}`)
+
+    const config = /** @type {YotoDeviceConfig} */ (await this.request(`/device-v2/${deviceId}/config`))
+    return config
+  }
+
+  /**
+   * Update device configuration
+   * @param {string} deviceId - Device ID
+   * @param {YotoDeviceConfig} config - Updated configuration
+   * @returns {Promise<YotoDeviceConfig>}
+   */
+  async updateDeviceConfig (deviceId, config) {
+    this.log.debug(LOG_PREFIX.API, `Updating config for device ${deviceId}`)
+
+    const updatedConfig = /** @type {YotoDeviceConfig} */ (await this.request(`/device-v2/${deviceId}/config`, {
+      method: 'PUT',
+      body: JSON.stringify(config)
+    }))
+
+    return updatedConfig
+  }
+
+  /**
+   * Get content/card details
+   * @param {string} cardId - Card ID
+   * @param {Object} [options] - Query options
+   * @param {string} [options.timezone] - Timezone for chapter availability
+   * @param {boolean} [options.playable] - Return playable signed URLs
+   * @returns {Promise<YotoCardContent>}
+   */
+  async getContent (cardId, options = {}) {
+    this.log.debug(LOG_PREFIX.API, `Fetching content for card ${cardId}`)
+
+    const queryParams = new URLSearchParams()
+    if (options.timezone) {
+      queryParams.append('timezone', options.timezone)
+    }
+    if (options.playable) {
+      queryParams.append('playable', 'true')
+    }
+
+    const queryString = queryParams.toString()
+    const endpoint = `/content/${cardId}${queryString ? `?${queryString}` : ''}`
+
+    const content = /** @type {YotoCardContent} */ (await this.request(endpoint))
+    return content
+  }
+
+  /**
+   * Get user's MYO (Make Your Own) cards
+   * @param {Object} [options] - Query options
+   * @param {boolean} [options.showdeleted] - Show deleted cards
+   * @returns {Promise<any>}
+   */
+  async getMyContent (options = {}) {
+    this.log.debug(LOG_PREFIX.API, 'Fetching user content...')
+
+    const queryParams = new URLSearchParams()
+    if (options.showdeleted !== undefined) {
+      queryParams.append('showdeleted', String(options.showdeleted))
+    }
+
+    const queryString = queryParams.toString()
+    const endpoint = `/content/mine${queryString ? `?${queryString}` : ''}`
+
+    const content = await this.request(endpoint)
+    return content
+  }
+
+  /**
+   * Get family library groups
+   * @returns {Promise<any>}
+   */
+  async getLibraryGroups () {
+    this.log.debug(LOG_PREFIX.API, 'Fetching library groups...')
+
+    const groups = await this.request('/card/family/library/groups')
+    return groups
+  }
+
+  /**
+   * Get specific library group
+   * @param {string} groupId - Group ID
+   * @returns {Promise<any>}
+   */
+  async getLibraryGroup (groupId) {
+    this.log.debug(LOG_PREFIX.API, `Fetching library group ${groupId}`)
+
+    const group = await this.request(`/card/family/library/groups/${groupId}`)
+    return group
+  }
+
+  /**
+   * Set callback for token refresh events
+   * @param {(accessToken: string, refreshToken: string, expiresAt: number) => void} callback
+   */
+  setTokenRefreshCallback (callback) {
+    this.onTokenRefreshCallback = callback
+  }
+}