@mdjhnson/homebridge-yoto 0.1.0

package/lib/service-config.js

@@ -0,0 +1,47 @@
+/** @import { PlatformConfig } from 'homebridge' */
+
+import { getBooleanSetting } from './utils/get-boolean-setting.js'
+import { serviceSchema } from '../config.schema.cjs'
+
+/**
+ * @typedef {Object} PlaybackAccessoryConfig
+ * @property {boolean} playbackEnabled
+ * @property {boolean} volumeEnabled
+ * @property {boolean} smartSpeakerEnabled
+ * @property {boolean} televisionEnabled
+ */
+
+/**
+ * @param {PlatformConfig} config
+ * @returns {PlaybackAccessoryConfig}
+ */
+export function getPlaybackAccessoryConfig (config) {
+  const services = config && typeof config === 'object' ? config['services'] : undefined
+  const serviceConfig = typeof services === 'object' && services !== null
+    ? /** @type {Record<string, unknown>} */ (services)
+    : {}
+
+  const playbackEnabled = getBooleanSetting(serviceConfig['playbackControls'], false)
+  const smartSpeakerEnabled = getBooleanSetting(serviceConfig['smartSpeaker'], false)
+  const televisionEnabled = getBooleanSetting(serviceConfig['television'], false)
+
+  return {
+    playbackEnabled,
+    volumeEnabled: playbackEnabled,
+    smartSpeakerEnabled,
+    televisionEnabled,
+  }
+}
+
+/**
+ * Whether shortcut controls are enabled (switches and TV inputs).
+ * @param {PlatformConfig} config
+ * @returns {boolean}
+ */
+export function getShortcutsEnabled (config) {
+  const services = config && typeof config === 'object' ? config['services'] : undefined
+  const serviceConfig = typeof services === 'object' && services !== null
+    ? /** @type {Record<string, unknown>} */ (services)
+    : {}
+  return getBooleanSetting(serviceConfig['shortcuts'], serviceSchema.shortcuts.default)
+}

package/lib/settings.js

@@ -0,0 +1,56 @@
+import { configSchema } from '../config.schema.cjs'
+
+/**
+ * This is the name of the platform that users will use to register the plugin in the Homebridge config.json
+ */
+export const PLATFORM_NAME = 'Yoto'
+
+/**
+ * This must match the name of your plugin as defined the package.json `name` property
+ */
+export const PLUGIN_NAME = '@mdjhnson/homebridge-yoto'
+
+/**
+ * Default OAuth Client ID from config schema
+ */
+export const DEFAULT_CLIENT_ID = configSchema.schema.properties.clientId.default
+
+/**
+ * OAuth redirect URI registered on the Yoto developer app. Nothing listens here:
+ * the user copies the resulting address back into the plugin settings.
+ */
+export const OAUTH_REDIRECT_URI = 'http://127.0.0.1:8787/callback'
+
+/**
+ * Client IDs from earlier versions that only support the retired device-code
+ * sign-in. Configs still using them are switched to DEFAULT_CLIENT_ID on sign-in.
+ */
+export const LEGACY_CLIENT_IDS = ['Y4HJ8BFqRQ24GQoLzgOzZ2KSqWmFG8LI']
+
+/**
+ * OAuth scopes requested during sign-in. The Yoto developer app must have the
+ * same scopes enabled in the dashboard.
+ * @see https://yoto.dev/authentication/scopes/
+ */
+export const OAUTH_SCOPES = [
+  'offline_access', // refresh tokens
+  'family:devices:view', // list players and read status
+  'family:devices:manage', // nightlight, volume limits, Bluetooth settings
+  'family:devices:control', // MQTT playback and volume control
+  'family:library:view', // card titles for shortcut names
+  'user:content:view', // titles of Make Your Own cards
+].join(' ')
+
+/** Device defaults */
+export const DEFAULT_MANUFACTURER = 'Yoto Inc.'
+export const DEFAULT_MODEL = 'Yoto Player'
+
+/** Battery threshold */
+export const LOW_BATTERY_THRESHOLD = 20
+
+/** Logging prefixes for debugging */
+export const LOG_PREFIX = {
+  PLATFORM: '[Platform]',
+  ACCESSORY: '[Accessory]',
+  MQTT: '[MQTT]',
+}

package/lib/shortcuts.js

@@ -0,0 +1,131 @@
+/** @import { YotoDeviceShortcuts } from 'yoto-nodejs-client/lib/api-endpoints/devices.js' */
+/** @import { PlayableCard } from './card-controls.js' */
+
+/**
+ * A playable shortcut configured on a Yoto device.
+ * @typedef {Object} ShortcutEntry
+ * @property {string} id - Stable identifier derived from the content it plays
+ * @property {number} number - 1-based position, used for fallback labels
+ * @property {Array<'day' | 'night'>} modes - Modes this shortcut is configured in
+ * @property {string} cardId - Card to play
+ * @property {string} [chapterKey] - Chapter to start at
+ * @property {string} [trackKey] - Track to start at (may contain a date placeholder; see resolveShortcutKey)
+ * @property {string} [builtInName] - Name for Yoto's built-in shortcuts (Daily, Radio)
+ */
+
+/** @type {Array<'day' | 'night'>} */
+const MODES = ['day', 'night']
+
+/**
+ * Names for Yoto's built-in shortcuts, keyed by chapter. These live on a system
+ * card whose title can't be looked up.
+ * @type {Record<string, string>}
+ */
+const BUILT_IN_SHORTCUT_NAMES = {
+  daily: 'Yoto Daily',
+  'radio-day': 'Yoto Radio',
+  'radio-night': 'Yoto Night Radio',
+}
+
+/**
+ * Replace date placeholders in shortcut chapter/track keys (e.g. Yoto Daily's
+ * `<yyyymmdd>` track) with the current local date.
+ * @param {string | undefined} key
+ * @param {Date} [now]
+ * @returns {string | undefined}
+ */
+export function resolveShortcutKey (key, now = new Date()) {
+  if (!key || !key.includes('<')) return key
+  const yyyy = String(now.getFullYear())
+  const mm = String(now.getMonth() + 1).padStart(2, '0')
+  const dd = String(now.getDate()).padStart(2, '0')
+  return key.replaceAll('<yyyymmdd>', `${yyyy}${mm}${dd}`)
+}
+
+/**
+ * Content to play for a shortcut, labelled for logs.
+ * @param {ShortcutEntry} entry
+ * @param {string} label
+ * @returns {PlayableCard}
+ */
+export function toPlayableCard (entry, label) {
+  return {
+    label,
+    cardId: entry.cardId,
+    ...(entry.chapterKey !== undefined && { chapterKey: entry.chapterKey }),
+    ...(entry.trackKey !== undefined && { trackKey: entry.trackKey }),
+  }
+}
+
+/**
+ * startCard() options for a playable card, with date placeholders resolved.
+ * @param {PlayableCard} card
+ * @param {Date} [now]
+ * @returns {{ cardId: string, chapterKey?: string, trackKey?: string }}
+ */
+export function getCardStartOptions (card, now = new Date()) {
+  const chapterKey = resolveShortcutKey(card.chapterKey, now)
+  const trackKey = resolveShortcutKey(card.trackKey, now)
+  return {
+    cardId: card.cardId,
+    ...(chapterKey !== undefined && { chapterKey }),
+    ...(trackKey !== undefined && { trackKey }),
+  }
+}
+
+/**
+ * Extract playable shortcuts from device shortcut config.
+ *
+ * The same content configured in both day and night mode is returned once.
+ * Only `track-play` commands with a card ID are supported.
+ *
+ * @param {YotoDeviceShortcuts | null | undefined} shortcuts
+ * @returns {ShortcutEntry[]}
+ */
+export function getShortcutEntries (shortcuts) {
+  /** @type {Map<string, ShortcutEntry>} */
+  const entries = new Map()
+
+  for (const mode of MODES) {
+    const content = shortcuts?.modes?.[mode]?.content
+    if (!Array.isArray(content)) continue
+
+    for (const item of content) {
+      if (!item || item.cmd !== 'track-play') continue
+      const cardId = typeof item.params?.card === 'string' ? item.params.card.trim() : ''
+      if (!cardId) continue
+
+      const chapterKey = typeof item.params.chapter === 'string' && item.params.chapter ? item.params.chapter : undefined
+      const trackKey = typeof item.params.track === 'string' && item.params.track ? item.params.track : undefined
+      const id = [cardId, chapterKey ?? '', trackKey ?? ''].join(':')
+
+      const existing = entries.get(id)
+      if (existing) {
+        if (!existing.modes.includes(mode)) existing.modes.push(mode)
+        continue
+      }
+
+      const builtInName = chapterKey ? BUILT_IN_SHORTCUT_NAMES[chapterKey] : undefined
+      entries.set(id, {
+        id,
+        number: entries.size + 1,
+        modes: [mode],
+        cardId,
+        ...(chapterKey !== undefined && { chapterKey }),
+        ...(trackKey !== undefined && { trackKey }),
+        ...(builtInName !== undefined && { builtInName }),
+      })
+    }
+  }
+
+  return Array.from(entries.values())
+}
+
+/**
+ * Signature used to detect when the set of shortcuts changes.
+ * @param {ShortcutEntry[]} entries
+ * @returns {string}
+ */
+export function getShortcutsSignature (entries) {
+  return entries.map(entry => entry.id).join('|')
+}