@mdjhnson/homebridge-yoto 0.1.4 → 0.1.5

package/README.md

@@ -21,7 +21,7 @@
 
 </span>
 
-Homebridge plugin that exposes Yoto players to HomeKit: playback and volume, card and shortcut buttons, battery, temperature, nightlights, and more. Updates arrive in real time over MQTT, with HTTP polling as a fallback.
+Homebridge plugin that exposes Yoto players to HomeKit: playback and volume, card and shortcut buttons, a TV-style remote with your card library as inputs, a sleep timer slider, battery, temperature, nightlights, and more. Updates arrive in real time over MQTT, with HTTP polling as a fallback.
 
 This is a maintained fork of [bcomnes/homebridge-yoto](https://github.com/bcomnes/homebridge-yoto).
 
@@ -44,7 +44,7 @@ Requires Node.js 22, 24 or 26 and Homebridge 1.8+ or 2.x.
 
 Using your own Yoto developer app? Make it a **Public Client**, add `http://127.0.0.1:8787/callback` as an allowed callback URL, enable the `family:devices:*`, `family:library:view`, `user:content:view` and `offline_access` scopes, and enter its client ID in the **Advanced Settings** panel on the sign-in screen before signing in. (That panel is only shown while you're signed out, and is separate from the **Advanced** section of the plugin settings.)
 
-The plugin asks for access to view, configure and control your players, plus read-only access to your card library (used to name shortcut switches). If you signed in with an older version, sign in again so the new permissions apply.
+The plugin asks for access to view, configure and control your players, plus read-only access to your card library (used to name shortcut switches and to list your cards as TV inputs). If you signed in with an older version, sign in again so the new permissions apply.
 
 The plugin refreshes its tokens on its own. If the login ever expires or is revoked, the Homebridge log will say so. Sign in again from the plugin settings.
 
@@ -54,7 +54,8 @@ Most options live under **Accessory Services** in the plugin settings. The setti
 
 **Playback**
 - **Playback Controls**: Adds a play/pause switch and a volume dimmer to each player's bridged accessory. This is the simplest option and needs no extra pairing.
-- **TV Playback Accessory**: Publishes a separate TV-style accessory. You control it with the iOS remote (play/pause, volume buttons), and its inputs play your card controls and shortcuts.
+- **TV Playback Accessory**: Publishes a separate TV-style accessory. You control it with the iOS remote (play/pause, volume buttons), and its inputs play your library cards, card controls and shortcuts.
+  - **TV Inputs for Library Cards** (on by default, shown once the TV accessory is on): lists every card in your Yoto library, including Make Your Own cards, as an input. Turn it off to list only card controls and shortcuts.
 
 The TV accessory, and the legacy Smart Speaker below, are external accessories. External accessories must be added by hand in the Home app (**Add Accessory → More options**) using the setup code in the Homebridge log. Each one listens on its own port (logged as `... is running on port N`), so open those ports if Homebridge runs behind a firewall, or set a fixed port range under Homebridge **Settings → Network**.
 
@@ -68,6 +69,7 @@ The TV accessory, and the legacy Smart Speaker below, are external accessories.
 
 **Service toggles**
 - **Battery**, **Temperature Sensor** (v3), **Nightlight** (v3), **Card Slot**, **Day Mode**, **Sleep Timer**, **Bluetooth**, **Volume Limits**.
+  - **Sleep Timer Minutes per 1%** (shown once Sleep Timer is on): how many minutes each 1% on the sleep timer slider stands for. Defaults to 1, so the slider goes up to 100 minutes; 2 allows up to 200 minutes. Accepts 0.5 to 10.
 
 **Advanced** (collapsed section at the bottom of the plugin settings)
 - **HTTP Poll Interval**: How often to poll the Yoto API as a fallback to MQTT. Defaults to 60 seconds; the minimum is 10 seconds.
@@ -84,7 +86,9 @@ The TV accessory, and the legacy Smart Speaker below, are external accessories.
 
 **TV Playback (external)**
 - Active is on while the player is playing. Turning it off pauses.
-- Inputs: **Now Playing**, then one per card control and one per shortcut. Choosing an input plays its card.
+- Inputs: **Now Playing**, then your card controls, shortcuts and library cards (including Make Your Own cards), listed alphabetically. Choosing an input plays its card.
+- HomeKit allows about 90 inputs. Card controls and shortcuts always get one; library cards fill the rest in alphabetical order, and the log says how many were left out. Turn off **TV Inputs for Library Cards** to list only card controls and shortcuts.
+- New library cards appear within about six hours, or after restarting Homebridge.
 - Remote: Play/Pause and Select toggle playback. Volume buttons step the volume.
 
 **Card Controls and Shortcuts**
@@ -102,13 +106,19 @@ The TV accessory, and the legacy Smart Speaker below, are external accessories.
 **Other controls**
 - **Card Slot**: Contact sensor for card insertion.
 - **Day Mode**: Contact sensor. Contact Not Detected means day mode.
-- **Sleep Timer**: Switch that turns the sleep timer on or off.
+- **Sleep Timer**: Lightbulb whose brightness is the time left on the sleep timer.
+  - Each 1% is one minute by default, so 45% is a 45-minute timer. Change **Sleep Timer Minutes per 1%** for longer timers.
+  - Turning it on without picking a time reuses the last time you set (30 minutes at first, and again after Homebridge restarts). Turning it off cancels the timer.
+  - It counts down while the timer runs and follows timers started in the Yoto app.
+  - Because it's a light, a "turn off all the lights" scene or Siri request also cancels the timer.
 - **Bluetooth**: Switch that toggles Bluetooth.
 - **Day/Night Max Volume**: Lightbulbs whose brightness sets the max volume limits.
 
 ## Notes
 
 - **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.
+- **Upgrading to the sleep timer slider:** the old on/off Sleep Timer switch is replaced by the slider, so add the slider back to any scenes or automations that used the switch.
+- **Upgrading to library TV inputs:** existing TV inputs get new identifiers once, so scenes that choose a TV input need that input picked again. After that, identifiers stay the same when cards are added or removed.
 - **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.
 

package/config.schema.json

@@ -73,7 +73,13 @@
             "title": "TV Playback Accessory",
             "type": "boolean",
             "default": false,
-            "description": "Publish an external TV-style accessory: play/pause and volume from the iPhone remote, and inputs that play your card controls and shortcuts. Requires pairing and its own network port."
+            "description": "Publish an external TV-style accessory: play/pause and volume from the iPhone remote, and inputs that play your cards, card controls and shortcuts. Requires pairing and its own network port."
+          },
+          "televisionLibrary": {
+            "title": "TV Inputs for Library Cards",
+            "type": "boolean",
+            "default": true,
+            "description": "Add every card in your Yoto library as a TV input, listed alphabetically. HomeKit allows about 90 inputs; if your library is bigger, cards past the limit are left out."
           },
           "battery": {
             "title": "Battery",
@@ -144,7 +150,15 @@
             "title": "Sleep Timer",
             "type": "boolean",
             "default": false,
-            "description": "Expose sleep timer switch."
+            "description": "Expose the sleep timer as a slider. Each 1% is one minute unless changed below; turning it on without a time uses 30 minutes."
+          },
+          "sleepTimerMinutesPerPercent": {
+            "title": "Sleep Timer Minutes per 1%",
+            "type": "number",
+            "default": 1,
+            "minimum": 0.5,
+            "maximum": 10,
+            "description": "How many minutes each 1% on the sleep timer slider adds. 1 gives up to 100 minutes; 2 gives up to 200 minutes."
           },
           "bluetooth": {
             "title": "Bluetooth",
@@ -192,6 +206,12 @@
         },
         "services.playbackControls",
         "services.television",
+        {
+          "key": "services.televisionLibrary",
+          "condition": {
+            "functionBody": "return model.services && model.services.television === true"
+          }
+        },
         "services.volumeLimits",
         "services.battery",
         "services.temperature",
@@ -200,6 +220,12 @@
         "services.nightlight",
         "services.bluetooth",
         "services.sleepTimer",
+        {
+          "key": "services.sleepTimerMinutesPerPercent",
+          "condition": {
+            "functionBody": "return model.services && model.services.sleepTimer === true"
+          }
+        },
         "services.shortcuts",
         {
           "type": "help",

package/lib/accessory.js

@@ -36,6 +36,7 @@
  * @property {boolean} shortcuts
  */
 
+import { setTimeout as delay } from 'node:timers/promises'
 import convert from 'color-convert'
 import {
   DEFAULT_MANUFACTURER,
@@ -46,7 +47,7 @@ import {
 import { sanitizeName } from './utils/sanitize-name.js'
 import { syncServiceNames } from './sync-service-names.js'
 import { serviceSchema } from '../config.schema.cjs'
-import { getPlaybackAccessoryConfig } from './service-config.js'
+import { getPlaybackAccessoryConfig, getServiceConfig, getSleepTimerIncrement } 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'
@@ -59,6 +60,27 @@ import {
   percentToSteps,
   stepsToPercent,
 } from './utils/volume.js'
+import {
+  DEFAULT_SLEEP_TIMER_MINUTES,
+  DEFAULT_SLEEP_TIMER_MINUTES_PER_PERCENT,
+  sleepPercentToSeconds,
+  sleepSecondsToPercent,
+} from './utils/sleep-timer.js'
+
+/**
+ * Dragging the slider on an off sleep timer makes Home send On=1 and then the
+ * brightness. Wait this long before starting the default timer so the
+ * brightness can set the time instead.
+ */
+const SLEEP_TIMER_ON_DELAY_MS = 250
+/** How often the sleep timer slider counts down between player reports */
+const SLEEP_TIMER_TICK_MS = 30 * 1000
+/**
+ * Players take a few seconds to apply a sleep timer command and keep sending
+ * the old state meanwhile. For this long after a command, ignore reports that
+ * don't match it.
+ */
+const SLEEP_TIMER_CONFIRM_MS = 10 * 1000
 
 /**
  * @param {ServiceSchemaKey} key
@@ -107,6 +129,15 @@ export class YotoPlayerAccessory {
   /** @type {ListenerGroup<YotoDeviceModelEventMap>} */ #listeners
   /** @type {Map<string, Service>} */ #shortcutServices = new Map()
   /** @type {string} */ #shortcutsSignature = ''
+  // Sleep timer: the player reports seconds left only now and then, so count
+  // down locally from the last report
+  /** @type {number} */ #sleepTimerIncrement = DEFAULT_SLEEP_TIMER_MINUTES_PER_PERCENT
+  /** @type {number | null} */ #sleepTimerEndsAt = null
+  /** @type {ReturnType<typeof setInterval> | null} */ #sleepTimerTick = null
+  /** @type {number} */ #lastSleepTimerPercent = DEFAULT_SLEEP_TIMER_MINUTES
+  /** @type {number} */ #sleepTimerRequest = 0
+  /** @type {{ seconds: number, sentAt: number } | null} */ #sleepTimerPending = null
+  /** @type {boolean} */ #stopped = false
 
   /**
    * @param {Object} params
@@ -135,11 +166,7 @@ export class YotoPlayerAccessory {
    * @returns {YotoServiceToggles}
    */
   getServiceToggles () {
-    const config = this.#platform.config
-    const services = config && typeof config === 'object' ? config['services'] : undefined
-    const serviceConfig = typeof services === 'object' && services !== null
-      ? /** @type {Record<string, unknown>} */ (services)
-      : {}
+    const serviceConfig = getServiceConfig(this.#platform.config)
     const playbackConfig = getPlaybackAccessoryConfig(this.#platform.config)
 
     return {
@@ -578,23 +605,32 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Setup sleep timer Switch service
-   * Toggle sleep timer on/off
+   * Setup sleep timer Lightbulb service
+   * On/off starts or cancels the timer; brightness is the time left
+   * (each 1% is `sleepTimerMinutesPerPercent` minutes).
+   * Replaces the Switch used by earlier versions, which setup() removes as stale.
    */
   setupSleepTimerService () {
     const { Service, Characteristic } = this.#platform
     const serviceName = this.generateServiceName('Sleep Timer')
+    this.#sleepTimerIncrement = getSleepTimerIncrement(this.#platform.config)
+    this.#lastSleepTimerPercent = sleepSecondsToPercent(DEFAULT_SLEEP_TIMER_MINUTES * 60, this.#sleepTimerIncrement)
 
-    const service = this.#accessory.getServiceById(Service.Switch, 'SleepTimer') ||
-      this.#accessory.addService(Service.Switch, serviceName, 'SleepTimer')
+    const service = this.#accessory.getServiceById(Service.Lightbulb, 'SleepTimer') ||
+      this.#accessory.addService(Service.Lightbulb, serviceName, 'SleepTimer')
     syncServiceNames({ Characteristic, service, name: serviceName })
 
     service.getCharacteristic(Characteristic.On)
       .onGet(this.getSleepTimerState.bind(this))
       .onSet(this.setSleepTimerState.bind(this))
 
+    service.getCharacteristic(Characteristic.Brightness)
+      .onGet(this.getSleepTimerPercent.bind(this))
+      .onSet(this.setSleepTimerPercent.bind(this))
+
     this.sleepTimerService = service
     this.#currentServices.add(service)
+    this.syncSleepTimerFromPlayback()
   }
 
   /**
@@ -1006,7 +1042,8 @@ export class YotoPlayerAccessory {
             break
 
           case 'sleepTimerActive':
-            this.updateSleepTimerCharacteristic()
+          case 'sleepTimerSeconds':
+            this.syncSleepTimerFromPlayback()
             break
 
           // Playback fields - informational only
@@ -1022,7 +1059,6 @@ export class YotoPlayerAccessory {
           case 'trackKey':
           case 'chapterTitle':
           case 'chapterKey':
-          case 'sleepTimerSeconds':
           case 'streaming':
           case 'updatedAt': {
             // Not exposed as characteristics
@@ -1784,44 +1820,163 @@ export class YotoPlayerAccessory {
       : Characteristic.ContactSensorState.CONTACT_DETECTED
   }
 
-  // ==================== Sleep Timer Switch Getter/Setter ====================
+  // ==================== Sleep Timer (Lightbulb) Getter/Setter ====================
+
+  /**
+   * Seconds left on the sleep timer, or null when the player hasn't said.
+   * @returns {number | null}
+   */
+  getSleepTimerRemainingSeconds () {
+    if (this.#sleepTimerEndsAt === null) return null
+    return Math.max(0, (this.#sleepTimerEndsAt - Date.now()) / 1000)
+  }
+
+  /**
+   * @returns {boolean}
+   */
+  isSleepTimerOn () {
+    const remaining = this.getSleepTimerRemainingSeconds()
+    if (remaining !== null) return remaining > 0
+    return this.#deviceModel.playback.sleepTimerActive === true
+  }
+
+  /**
+   * Slider position: the time left while running, otherwise the last time set.
+   * @returns {number}
+   */
+  getSleepTimerPercentValue () {
+    const remaining = this.getSleepTimerRemainingSeconds()
+    if (remaining !== null && remaining > 0) {
+      return sleepSecondsToPercent(remaining, this.#sleepTimerIncrement)
+    }
+    return this.#lastSleepTimerPercent
+  }
 
   /**
    * Get sleep timer state
    * @returns {Promise<CharacteristicValue>}
    */
   async getSleepTimerState () {
-    const playback = this.#deviceModel.playback
-    this.#log.debug(
-      LOG_PREFIX.ACCESSORY,
-      `[${this.#device.name}] Get sleep timer -> ${playback.sleepTimerActive ?? false}`
-    )
-    return playback.sleepTimerActive ?? false
+    const on = this.isSleepTimerOn()
+    this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Get sleep timer -> ${on}`)
+    return on
   }
 
   /**
-   * Set sleep timer state
+   * Set sleep timer state. On starts the last time used (30 minutes at first).
    * @param {CharacteristicValue} value
    */
   async setSleepTimerState (value) {
-    const enabled = Boolean(value)
+    if (!value) {
+      this.#sleepTimerRequest++
+      await this.applySleepTimer(0)
+      return
+    }
+    if (this.isSleepTimerOn()) return
+
+    const request = ++this.#sleepTimerRequest
+    await delay(SLEEP_TIMER_ON_DELAY_MS)
+    // The slider was moved meanwhile; it sets the time itself
+    if (request !== this.#sleepTimerRequest) return
+    await this.applySleepTimer(this.#lastSleepTimerPercent)
+  }
+
+  /**
+   * Get sleep timer slider position
+   * @returns {Promise<CharacteristicValue>}
+   */
+  async getSleepTimerPercent () {
+    return this.getSleepTimerPercentValue()
+  }
+
+  /**
+   * Set sleep timer length from the slider
+   * @param {CharacteristicValue} value
+   */
+  async setSleepTimerPercent (value) {
+    this.#sleepTimerRequest++
+    const percent = clampPercent(Number(value))
+    if (percent > 0) this.#lastSleepTimerPercent = percent
+    await this.applySleepTimer(percent)
+  }
+
+  /**
+   * Send a sleep timer length to the player (0 cancels it).
+   * @param {number} percent
+   */
+  async applySleepTimer (percent) {
+    const seconds = sleepPercentToSeconds(percent, this.#sleepTimerIncrement)
+    this.#log.debug(
+      LOG_PREFIX.ACCESSORY,
+      `[${this.#device.name}] Set sleep timer: ${seconds > 0 ? `${Math.round(seconds / 60)} minutes` : 'off'}`
+    )
 
     try {
-      if (enabled) {
-        // Turn on sleep timer - default to 30 minutes
-        this.#log.debug(LOG_PREFIX.ACCESSORY, 'Activating sleep timer (30 minutes)')
-        await this.#deviceModel.setSleepTimer(30 * 60)
-      } else {
-        // Turn off sleep timer
-        this.#log.debug(LOG_PREFIX.ACCESSORY, 'Deactivating sleep timer')
-        await this.#deviceModel.setSleepTimer(0)
-      }
+      await this.#deviceModel.setSleepTimer(seconds)
     } catch (error) {
       this.#log.error(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Failed to set sleep timer:`, formatError(error))
       throw new this.#platform.api.hap.HapStatusError(
         this.#platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE
       )
     }
+
+    // Show the new time now rather than waiting for the player to report it.
+    // A cancel ends "now", so the tile doesn't flick back on while the player's
+    // last report still says the timer is running.
+    this.#sleepTimerPending = { seconds, sentAt: Date.now() }
+    this.setSleepTimerEnd(Date.now() + seconds * 1000)
+  }
+
+  /**
+   * Take the sleep timer state the player last reported.
+   */
+  syncSleepTimerFromPlayback () {
+    if (!this.sleepTimerService) return
+    const { sleepTimerActive, sleepTimerSeconds } = this.#deviceModel.playback
+
+    const pending = this.#sleepTimerPending
+    if (pending) {
+      const age = Date.now() - pending.sentAt
+      const expectedSeconds = pending.seconds - age / 1000
+      const confirmed = pending.seconds === 0
+        ? sleepTimerActive !== true
+        : sleepTimerActive === true && typeof sleepTimerSeconds === 'number' &&
+          Math.abs(sleepTimerSeconds - expectedSeconds) <= 5
+      // A report from before the player applied our command
+      if (!confirmed && age < SLEEP_TIMER_CONFIRM_MS) return
+      this.#sleepTimerPending = null
+    }
+
+    if (sleepTimerActive === true && typeof sleepTimerSeconds === 'number' && sleepTimerSeconds > 0) {
+      this.setSleepTimerEnd(Date.now() + sleepTimerSeconds * 1000)
+    } else if (sleepTimerActive !== true) {
+      this.setSleepTimerEnd(null)
+    } else {
+      // Running, but the player hasn't said how long is left. Drop an end time
+      // that has passed (e.g. from a cancel) so the tile follows the player.
+      if (this.getSleepTimerRemainingSeconds() === 0) this.#sleepTimerEndsAt = null
+      this.updateSleepTimerCharacteristic()
+    }
+  }
+
+  /**
+   * Record when the sleep timer ends and count the slider down until then.
+   * @param {number | null} endsAt - Epoch ms, or null when off
+   */
+  setSleepTimerEnd (endsAt) {
+    this.#sleepTimerEndsAt = endsAt
+    if (endsAt !== null && !this.#sleepTimerTick && !this.#stopped) {
+      this.#sleepTimerTick = setInterval(() => this.updateSleepTimerCharacteristic(), SLEEP_TIMER_TICK_MS)
+      this.#sleepTimerTick.unref?.()
+    }
+    this.updateSleepTimerCharacteristic()
+  }
+
+  stopSleepTimerTick () {
+    if (this.#sleepTimerTick) {
+      clearInterval(this.#sleepTimerTick)
+      this.#sleepTimerTick = null
+    }
   }
 
   // ==================== Bluetooth Switch Getter/Setter ====================
@@ -2248,19 +2403,18 @@ export class YotoPlayerAccessory {
   }
 
   /**
-   * Update sleep timer Switch characteristic
+   * Update sleep timer On and Brightness characteristics
    */
   updateSleepTimerCharacteristic () {
+    const on = this.isSleepTimerOn()
+    if (!on) this.stopSleepTimerTick()
     if (!this.sleepTimerService) {
       return
     }
 
     const { Characteristic } = this.#platform
-    const playback = this.#deviceModel.playback
-
-    this.sleepTimerService
-      .getCharacteristic(Characteristic.On)
-      .updateValue(playback.sleepTimerActive ?? false)
+    this.sleepTimerService.updateCharacteristic(Characteristic.On, on)
+    this.sleepTimerService.updateCharacteristic(Characteristic.Brightness, this.getSleepTimerPercentValue())
   }
 
   /**
@@ -2347,6 +2501,10 @@ export class YotoPlayerAccessory {
 
     // Only remove our own listeners; the device model is shared
     this.#listeners.removeAll()
+    // Drop a pending "On" so this handler doesn't start a timer after it's replaced
+    this.#sleepTimerRequest++
+    this.#stopped = true
+    this.stopSleepTimerTick()
 
     // Note: Don't call deviceModel.stop() here - that's handled by YotoAccount
   }

package/lib/card-controls.js

@@ -19,16 +19,14 @@
 
 import { getTrimmedString } from './utils/get-trimmed-string.js'
 import { getBooleanSetting } from './utils/get-boolean-setting.js'
+import { getServiceConfig } from './service-config.js'
 
 /**
  * @param {PlatformConfig} config
  * @returns {CardControlConfig[]}
  */
 export function getCardControlConfigs (config) {
-  const services = config && typeof config === 'object' ? config['services'] : undefined
-  const serviceConfig = typeof services === 'object' && services !== null
-    ? /** @type {Record<string, unknown>} */ (services)
-    : {}
+  const serviceConfig = getServiceConfig(config)
 
   const rawControls = Array.isArray(serviceConfig['cardControls'])
     ? serviceConfig['cardControls']

package/lib/platform.js

@@ -8,6 +8,7 @@
 /** @import { YotoAccountEventMap } from 'yoto-nodejs-client/lib/yoto-account.js' */
 /** @import { PlaybackAccessoryConfig } from './service-config.js' */
 /** @import { CardControlConfig } from './card-controls.js' */
+/** @import { LibraryCard } from './utils/library.js' */
 
 /**
  * Context stored in PlatformAccessory for Yoto devices
@@ -23,6 +24,7 @@
  * @property {'card-control'} type - Accessory type marker
  */
 
+import { readFileSync } from 'node:fs'
 import { readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
 import { YotoAccount } from 'yoto-nodejs-client'
 import { randomUUID } from 'node:crypto'
@@ -41,13 +43,17 @@ import { getPlaybackAccessoryConfig } from './service-config.js'
 import { getCardControlConfigs } from './card-controls.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 { applyTokenUpdate, findNewerSavedTokens } from './utils/token-config.js'
 import { tolerateMissingStatusScope } from './utils/status-scope-fallback.js'
+import { getTokenClientId } from './utils/token-client-id.js'
+import { fetchFamilyLibrary } from './utils/library.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
+/** How long a fetched card library is reused (shared by all TV accessories) */
+const LIBRARY_CACHE_MS = 10 * 60 * 1000
 
 /**
  * Whether a failed account start could succeed if tried again. Network errors
@@ -86,6 +92,7 @@ export class YotoPlatform {
   /** @type {ListenerGroup<YotoAccountEventMap> | null} */ accountListeners = null
   /** @type {string} */ sessionId = randomUUID()
   /** @type {Map<string, Promise<string | null>>} */ cardTitleCache = new Map()
+  /** @type {{ fetchedAt: number, cards: Promise<LibraryCard[]> } | null} */ libraryCache = null
   /** @type {boolean} */ authInvalid = false
   /** @type {number} */ startRetryCount = 0
   /** @type {ReturnType<typeof setTimeout> | null} */ startRetryTimer = null
@@ -106,10 +113,22 @@ export class YotoPlatform {
 
     log.debug('Finished initializing platform:', config.name)
 
+    // A child bridge restarted after its process exits gets the config Homebridge
+    // read at startup, which can hold tokens already rotated by a refresh
+    this.useNewerSavedTokens(config)
+
     // Extract auth tokens once
-    const clientId = config['clientId'] || DEFAULT_CLIENT_ID
     const refreshToken = config['refreshToken']
     const accessToken = config['accessToken']
+    // Refreshing needs the client ID the tokens were issued to. The saved
+    // clientId can be stale: the settings form can save an old value back
+    // after signing in with another app.
+    const configuredClientId = config['clientId'] || DEFAULT_CLIENT_ID
+    const tokenClientId = getTokenClientId(accessToken)
+    const clientId = tokenClientId || configuredClientId
+    if (tokenClientId && tokenClientId !== configuredClientId) {
+      log.info(`Using the client ID your Yoto login was issued to (${tokenClientId}) instead of the one in the settings (${configuredClientId}).`)
+    }
 
     // Debug: Log what we found (redacted)
     log.debug('Config check - Has refreshToken:', !!refreshToken)
@@ -527,6 +546,38 @@ export class YotoPlatform {
     return lookup
   }
 
+  /**
+   * Cards in the family library (Make Your Own cards included), for TV inputs.
+   * Cached briefly. Rejects if the library can't be read, so callers keep the
+   * inputs they have; a failure isn't cached.
+   * @returns {Promise<LibraryCard[]>}
+   */
+  getLibraryCards () {
+    const now = Date.now()
+    if (this.libraryCache && now - this.libraryCache.fetchedAt < LIBRARY_CACHE_MS) {
+      return this.libraryCache.cards
+    }
+
+    const client = this.yotoAccount?.client
+    if (!client) return Promise.reject(new Error('Not signed in to Yoto'))
+
+    const cards = fetchFamilyLibrary(client).then(cards => {
+      for (const card of cards) {
+        if (!this.cardTitleCache.has(card.cardId)) {
+          this.cardTitleCache.set(card.cardId, Promise.resolve(card.title))
+        }
+      }
+      this.log.debug(`Loaded ${cards.length} library card(s) for TV inputs`)
+      return cards
+    })
+    cards.catch(error => {
+      if (this.libraryCache?.cards === cards) this.libraryCache = null
+      this.log.warn(`Could not load the Yoto card library for TV inputs (${errorMessage(error)}).`)
+    })
+    this.libraryCache = { fetchedAt: now, cards }
+    return cards
+  }
+
   /**
    * @param {string} deviceId
    * @returns {string}
@@ -624,10 +675,6 @@ export class YotoPlatform {
         existingAccessory.category = accessoryCategory
       }
 
-      // Update accessory information
-      this.api.updatePlatformAccessories([existingAccessory])
-      this.log.debug('Updated accessory cache entry:', existingAccessory.displayName, existingAccessory.UUID)
-
       // Create handler for this accessory with device model
       const handler = new YotoPlayerAccessory({
         platform: this,
@@ -643,6 +690,11 @@ export class YotoPlatform {
       await handler.setup()
       this.log.debug('Accessory setup complete:', existingAccessory.displayName)
 
+      // Save the cache after setup, so services it added or removed (e.g. the
+      // old sleep timer Switch) are kept on the next start
+      this.api.updatePlatformAccessories([existingAccessory])
+      this.log.debug('Updated accessory cache entry:', existingAccessory.displayName, existingAccessory.UUID)
+
       if (this.playbackAccessoryConfig.smartSpeakerEnabled) {
         await this.registerSpeakerAccessory(device, deviceModel)
       }
@@ -1092,6 +1144,30 @@ export class YotoPlatform {
     this.log.debug('✓ Yoto platform shutdown complete')
   }
 
+  /**
+   * Replace the tokens in `config` with newer ones saved in config.json, if any.
+   * @param {PlatformConfig} config
+   */
+  useNewerSavedTokens (config) {
+    try {
+      const bridge = config['_bridge']
+      const bridgeUsername = bridge && typeof bridge === 'object' && typeof bridge.username === 'string'
+        ? bridge.username
+        : undefined
+      const saved = findNewerSavedTokens(readFileSync(this.api.user.configPath(), 'utf8'), {
+        platform: PLATFORM_NAME,
+        ...(bridgeUsername && { bridgeUsername }),
+        refreshToken: config['refreshToken'],
+        tokenExpiresAt: config['tokenExpiresAt'],
+      })
+      if (!saved) return
+      this.log.debug('Using the newer tokens saved in config.json')
+      Object.assign(config, saved)
+    } catch (error) {
+      this.log.debug('Could not read saved tokens from config.json:', errorMessage(error))
+    }
+  }
+
   /**
    * Update Homebridge config.json file
    * @param {(configContents: string) => string | null} updateFn - Returns updated contents, or null if it could not apply the update

package/lib/service-config.js

@@ -2,6 +2,19 @@
 
 import { getBooleanSetting } from './utils/get-boolean-setting.js'
 import { serviceSchema } from '../config.schema.cjs'
+import { getSleepTimerMinutesPerPercent } from './utils/sleep-timer.js'
+
+/**
+ * The `services` section of the platform config, or {} if missing.
+ * @param {PlatformConfig} config
+ * @returns {Record<string, unknown>}
+ */
+export function getServiceConfig (config) {
+  const services = config && typeof config === 'object' ? config['services'] : undefined
+  return typeof services === 'object' && services !== null
+    ? /** @type {Record<string, unknown>} */ (services)
+    : {}
+}
 
 /**
  * @typedef {Object} PlaybackAccessoryConfig
@@ -16,10 +29,7 @@ import { serviceSchema } from '../config.schema.cjs'
  * @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 serviceConfig = getServiceConfig(config)
 
   const playbackEnabled = getBooleanSetting(serviceConfig['playbackControls'], false)
   const smartSpeakerEnabled = getBooleanSetting(serviceConfig['smartSpeaker'], false)
@@ -39,9 +49,23 @@ export function getPlaybackAccessoryConfig (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)
+  return getBooleanSetting(getServiceConfig(config)['shortcuts'], serviceSchema.shortcuts.default)
+}
+
+/**
+ * Whether the TV lists library cards as inputs.
+ * @param {PlatformConfig} config
+ * @returns {boolean}
+ */
+export function getTelevisionLibraryEnabled (config) {
+  return getBooleanSetting(getServiceConfig(config)['televisionLibrary'], serviceSchema.televisionLibrary.default)
+}
+
+/**
+ * Minutes each 1% on the sleep timer slider stands for.
+ * @param {PlatformConfig} config
+ * @returns {number}
+ */
+export function getSleepTimerIncrement (config) {
+  return getSleepTimerMinutesPerPercent(getServiceConfig(config)['sleepTimerMinutesPerPercent'])
 }

package/lib/television-accessory.js

@@ -9,6 +9,7 @@
 /** @import { YotoDevice } from 'yoto-nodejs-client/lib/api-endpoints/devices.js' */
 /** @import { YotoAccessoryContext } from './platform.js' */
 /** @import { PlayableCard } from './card-controls.js' */
+/** @import { LibraryCard } from './utils/library.js' */
 
 /**
  * A TV input and the content it plays (null for the "now playing" input).
@@ -17,6 +18,16 @@
  * @property {PlayableCard | null} card
  */
 
+/**
+ * An input other than "now playing", before it gets an identifier.
+ * @typedef {Object} InputSpec
+ * @property {string} subtype
+ * @property {string} name
+ * @property {PlayableCard} card
+ * @property {boolean} forceName - Apply the name even if the input already exists
+ * @property {boolean} resolveName - Rename to the card title once known
+ */
+
 import { setTimeout as delay } from 'node:timers/promises'
 import {
   DEFAULT_MANUFACTURER,
@@ -31,7 +42,8 @@ import { setDeviceVolume } from './utils/set-device-volume.js'
 import { getTrimmedString } from './utils/get-trimmed-string.js'
 import { getCardControlConfigs } from './card-controls.js'
 import { getCardStartOptions, getShortcutEntries, getShortcutsSignature, toPlayableCard } from './shortcuts.js'
-import { getShortcutsEnabled } from './service-config.js'
+import { getShortcutsEnabled, getTelevisionLibraryEnabled } from './service-config.js'
+import { allocateInputIdentifiers, encodeDisplayOrder, sortByName } from './utils/input-order.js'
 import {
   clampPercent,
   clampSteps,
@@ -42,7 +54,15 @@ import {
 
 /** Identifier of the input that represents whatever is currently playing */
 const NOW_PLAYING_INPUT_ID = 1
-const INPUT_SUBTYPE_PREFIXES = ['CardInput:', 'ShortcutInput:']
+const LIBRARY_INPUT_PREFIX = 'LibraryInput:'
+const INPUT_SUBTYPE_PREFIXES = ['CardInput:', 'ShortcutInput:', LIBRARY_INPUT_PREFIX]
+/**
+ * Most inputs to publish, "now playing" included. HAP allows 100 services per
+ * accessory, and the TV also needs its information, TV and speaker services.
+ */
+const MAX_TV_INPUTS = 90
+/** How often to look for cards added to the library */
+const LIBRARY_REFRESH_MS = 6 * 60 * 60 * 1000
 /**
  * Picking an input while the TV is off makes Home send Active=1 and then the
  * input. Wait this long before resuming so a picked input can cancel the resume.
@@ -68,6 +88,11 @@ export class YotoTelevisionAccessory {
   /** @type {Map<number, TelevisionInput>} */ #inputs = new Map()
   /** @type {string} */ #shortcutsSignature = ''
   /** @type {number} */ #resumeRequest = 0
+  /** @type {LibraryCard[] | null} */ #libraryCards = null
+  /** @type {string} */ #librarySignature = ''
+  /** @type {number} */ #omittedLibraryCards = 0
+  /** @type {ReturnType<typeof setInterval> | null} */ #libraryRefreshTimer = null
+  /** @type {boolean} */ #stopped = false
 
   /**
    * @param {Object} params
@@ -114,6 +139,12 @@ export class YotoTelevisionAccessory {
 
     this.setupEventListeners()
 
+    if (getTelevisionLibraryEnabled(this.#platform.config)) {
+      this.loadLibraryInputs()
+      this.#libraryRefreshTimer = setInterval(() => this.loadLibraryInputs(), LIBRARY_REFRESH_MS)
+      this.#libraryRefreshTimer.unref?.()
+    }
+
     this.#log.debug(LOG_PREFIX.ACCESSORY, `✓ ${this.#device.name} playback ready`)
   }
 
@@ -227,21 +258,27 @@ export class YotoTelevisionAccessory {
   }
 
   /**
-   * Setup InputSource services: "now playing", configured card controls, and
-   * (when enabled) device shortcuts. Removes inputs that no longer exist.
+   * Setup InputSource services: "now playing", configured card controls,
+   * (when enabled) device shortcuts, then library cards up to the HomeKit
+   * limit. Removes inputs that no longer exist.
    */
   setupInputSources () {
-    /** @type {Map<number, TelevisionInput>} */
-    const inputs = new Map()
-    let identifier = NOW_PLAYING_INPUT_ID
+    const { Service, Characteristic } = this.#platform
 
-    const nowPlaying = this.configureInputSource('PlaybackInput', identifier, `${this.#device.name} Now Playing`)
-    inputs.set(identifier, { service: nowPlaying, card: null })
+    /** @type {InputSpec[]} */
+    const specs = []
+    /** Cards already reachable from start, so the library doesn't repeat them */
+    const wholeCardIds = new Set()
 
     for (const control of getCardControlConfigs(this.#platform.config)) {
-      identifier += 1
-      const service = this.configureInputSource(`CardInput:${control.id}`, identifier, control.label)
-      inputs.set(identifier, { service, card: { label: control.label, cardId: control.cardId } })
+      specs.push({
+        subtype: `CardInput:${control.id}`,
+        name: control.label,
+        card: { label: control.label, cardId: control.cardId },
+        forceName: false,
+        resolveName: false,
+      })
+      wholeCardIds.add(control.cardId)
     }
 
     const shortcuts = getShortcutsEnabled(this.#platform.config)
@@ -250,12 +287,66 @@ export class YotoTelevisionAccessory {
     this.#shortcutsSignature = getShortcutsSignature(shortcuts)
 
     for (const entry of shortcuts) {
-      identifier += 1
       const fallbackName = entry.builtInName ?? `Shortcut ${entry.number}`
-      const service = this.configureInputSource(`ShortcutInput:${entry.id}`, identifier, fallbackName, Boolean(entry.builtInName))
-      const card = toPlayableCard(entry, fallbackName)
-      inputs.set(identifier, { service, card })
-      if (!entry.builtInName) this.resolveInputName(service, card)
+      specs.push({
+        subtype: `ShortcutInput:${entry.id}`,
+        name: fallbackName,
+        card: toPlayableCard(entry, fallbackName),
+        forceName: Boolean(entry.builtInName),
+        resolveName: !entry.builtInName,
+      })
+      if (!entry.chapterKey && !entry.trackKey) wholeCardIds.add(entry.cardId)
+    }
+
+    // Library cards fill the remaining inputs, alphabetically
+    const libraryCards = sortByName(
+      this.getLibraryInputCards()
+        .filter(card => !wholeCardIds.has(card.cardId))
+        .map(card => ({ ...card, name: card.title }))
+    )
+    const room = Math.max(0, MAX_TV_INPUTS - 1 - specs.length)
+    for (const libraryCard of libraryCards.slice(0, room)) {
+      specs.push({
+        subtype: `${LIBRARY_INPUT_PREFIX}${libraryCard.cardId}`,
+        name: libraryCard.title,
+        card: { label: libraryCard.title, cardId: libraryCard.cardId },
+        forceName: true,
+        resolveName: false,
+      })
+    }
+    const omitted = libraryCards.length - Math.min(room, libraryCards.length)
+    if (omitted > 0 && omitted !== this.#omittedLibraryCards) {
+      this.#log.warn(
+        LOG_PREFIX.ACCESSORY,
+        `[${this.#device.name}] HomeKit allows ${MAX_TV_INPUTS} TV inputs, so ${omitted} library card(s) were left out (the last ones alphabetically). Add a card control for any you need.`
+      )
+    }
+    this.#omittedLibraryCards = omitted
+
+    // Inputs that already exist keep their identifiers, so Home scenes do too
+    /** @type {Map<string, number>} */
+    const currentIdentifiers = new Map()
+    for (const service of this.#accessory.services) {
+      if (service.UUID !== Service.InputSource.UUID || !service.subtype) continue
+      const identifier = service.getCharacteristic(Characteristic.Identifier).value
+      if (typeof identifier === 'number') currentIdentifiers.set(service.subtype, identifier)
+    }
+    const identifiers = allocateInputIdentifiers(
+      specs.map(spec => spec.subtype),
+      currentIdentifiers,
+      [NOW_PLAYING_INPUT_ID]
+    )
+
+    /** @type {Map<number, TelevisionInput>} */
+    const inputs = new Map()
+    const nowPlaying = this.configureInputSource('PlaybackInput', NOW_PLAYING_INPUT_ID, `${this.#device.name} Now Playing`)
+    inputs.set(NOW_PLAYING_INPUT_ID, { service: nowPlaying, card: null })
+
+    for (const spec of specs) {
+      const identifier = /** @type {number} */ (identifiers.get(spec.subtype))
+      const service = this.configureInputSource(spec.subtype, identifier, spec.name, spec.forceName)
+      inputs.set(identifier, { service, card: spec.card })
+      if (spec.resolveName) this.resolveInputName(service, spec.card)
     }
 
     // Drop inputs that are no longer configured
@@ -271,6 +362,66 @@ export class YotoTelevisionAccessory {
 
     this.#inputs = inputs
     this.inputSourceService = nowPlaying
+    this.updateDisplayOrder()
+    this.updateActiveIdentifierCharacteristic()
+  }
+
+  /**
+   * Library cards to list as inputs. Until the library has loaded, these are
+   * the library inputs already published (a re-attached handler), so they
+   * aren't removed and added again.
+   * @returns {LibraryCard[]}
+   */
+  getLibraryInputCards () {
+    if (!getTelevisionLibraryEnabled(this.#platform.config)) return []
+    if (this.#libraryCards) return this.#libraryCards
+
+    const { Characteristic } = this.#platform
+    /** @type {LibraryCard[]} */
+    const published = []
+    for (const service of this.#accessory.services) {
+      const subtype = service.subtype ?? ''
+      if (!subtype.startsWith(LIBRARY_INPUT_PREFIX)) continue
+      const title = service.getCharacteristic(Characteristic.ConfiguredName).value
+      if (typeof title === 'string' && title) {
+        published.push({ cardId: subtype.slice(LIBRARY_INPUT_PREFIX.length), title })
+      }
+    }
+    return published
+  }
+
+  /**
+   * Fetch the card library and rebuild the inputs if it changed. If it can't
+   * be read, the current inputs stay.
+   */
+  loadLibraryInputs () {
+    this.#platform.getLibraryCards().then(cards => {
+      if (this.#stopped) return
+      const signature = cards.map(card => `${card.cardId}\u0000${card.title}`).join('\u0001')
+      if (this.#libraryCards && signature === this.#librarySignature) return
+      this.#librarySignature = signature
+      this.#libraryCards = cards
+      this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Library changed, updating TV inputs`)
+      this.setupInputSources()
+    }).catch(error => {
+      this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Keeping the current library TV inputs:`, formatError(error))
+    })
+  }
+
+  /**
+   * List inputs alphabetically in the Home app, with "now playing" first.
+   */
+  updateDisplayOrder () {
+    if (!this.televisionService) return
+    const { Characteristic } = this.#platform
+    const named = []
+    for (const [identifier, input] of this.#inputs) {
+      if (identifier === NOW_PLAYING_INPUT_ID) continue
+      const name = input.service.getCharacteristic(Characteristic.ConfiguredName).value
+      named.push({ identifier, name: typeof name === 'string' ? name : '' })
+    }
+    const order = [NOW_PLAYING_INPUT_ID, ...sortByName(named).map(input => input.identifier)]
+    this.televisionService.updateCharacteristic(Characteristic.DisplayOrder, encodeDisplayOrder(order))
   }
 
   /**
@@ -340,6 +491,7 @@ export class YotoTelevisionAccessory {
       service
         .updateCharacteristic(Characteristic.Name, name)
         .updateCharacteristic(Characteristic.ConfiguredName, name)
+      this.updateDisplayOrder()
     }).catch(error => {
       this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Failed to name TV input:`, formatError(error))
     })
@@ -508,7 +660,6 @@ export class YotoTelevisionAccessory {
       if (signature === this.#shortcutsSignature) return
       this.#log.debug(LOG_PREFIX.ACCESSORY, `[${this.#device.name}] Shortcuts changed, updating TV inputs`)
       this.setupInputSources()
-      this.updateActiveIdentifierCharacteristic()
     })
 
     this.#listeners.on('online', ({ reason: _reason }) => {
@@ -986,5 +1137,10 @@ export class YotoTelevisionAccessory {
     this.#listeners.removeAll()
     // Drop any pending resume
     this.#resumeRequest++
+    this.#stopped = true
+    if (this.#libraryRefreshTimer) {
+      clearInterval(this.#libraryRefreshTimer)
+      this.#libraryRefreshTimer = null
+    }
   }
 }

package/lib/utils/input-order.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview TV input identifiers and display order.
+ */
+
+/** Identifiers from here up are derived from the input subtype */
+const FIRST_HASHED_IDENTIFIER = 2
+const IDENTIFIER_RANGE = 999_998
+
+/**
+ * Pick a stable identifier for an input, so Home scenes that select an input
+ * keep pointing at the same card when other inputs are added or removed.
+ * Collisions move to the next free identifier.
+ * @param {string} subtype
+ * @param {Set<number>} used - Identifiers already taken (updated in place)
+ * @returns {number}
+ */
+export function allocateInputIdentifier (subtype, used) {
+  // FNV-1a
+  let hash = 0x811c9dc5
+  for (let i = 0; i < subtype.length; i++) {
+    hash ^= subtype.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193) >>> 0
+  }
+
+  let offset = hash % IDENTIFIER_RANGE
+  while (used.has(FIRST_HASHED_IDENTIFIER + offset)) {
+    offset = (offset + 1) % IDENTIFIER_RANGE
+  }
+  const identifier = FIRST_HASHED_IDENTIFIER + offset
+  used.add(identifier)
+  return identifier
+}
+
+/**
+ * Pick identifiers for a set of inputs. An input that already has one keeps
+ * it, so adding or removing other inputs never moves it (a hash collision
+ * would otherwise depend on which inputs exist). New inputs get one from
+ * `allocateInputIdentifier`.
+ * @param {string[]} subtypes - Inputs to identify, in allocation order
+ * @param {Map<string, number>} current - Identifiers the inputs already have
+ * @param {Iterable<number>} reserved - Identifiers no input may take
+ * @returns {Map<string, number>} Identifier by subtype
+ */
+export function allocateInputIdentifiers (subtypes, current, reserved) {
+  const used = new Set(reserved)
+  /** @type {Map<string, number>} */
+  const result = new Map()
+  for (const subtype of subtypes) {
+    const identifier = current.get(subtype)
+    if (identifier !== undefined && identifier >= FIRST_HASHED_IDENTIFIER && !used.has(identifier)) {
+      result.set(subtype, identifier)
+      used.add(identifier)
+    }
+  }
+  for (const subtype of subtypes) {
+    if (!result.has(subtype)) result.set(subtype, allocateInputIdentifier(subtype, used))
+  }
+  return result
+}
+
+/**
+ * Encode the Television DisplayOrder characteristic: one TLV entry (type 1,
+ * uint32 little-endian identifier) per input, separated by empty TLVs.
+ * @param {number[]} identifiers - In display order
+ * @returns {string} Base64 TLV8
+ */
+export function encodeDisplayOrder (identifiers) {
+  /** @type {Buffer[]} */
+  const parts = []
+  identifiers.forEach((identifier, index) => {
+    if (index > 0) parts.push(Buffer.from([0x00, 0x00]))
+    const entry = Buffer.alloc(6)
+    entry.writeUInt8(0x01, 0)
+    entry.writeUInt8(4, 1)
+    entry.writeUInt32LE(identifier, 2)
+    parts.push(entry)
+  })
+  return Buffer.concat(parts).toString('base64')
+}
+
+const collator = new Intl.Collator(undefined, { sensitivity: 'base', numeric: true })
+
+/**
+ * Sort alphabetically by name, ignoring case and accents, with numbers in
+ * numeric order ("Book 2" before "Book 10").
+ * @template {{ name: string }} T
+ * @param {T[]} items
+ * @returns {T[]}
+ */
+export function sortByName (items) {
+  return [...items].sort((a, b) => collator.compare(a.name, b.name))
+}

package/lib/utils/library.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Family card library lookup for TV inputs.
+ */
+
+/** @import { YotoClient } from 'yoto-nodejs-client' */
+
+import { YOTO_API_URL } from 'yoto-nodejs-client/lib/api-endpoints/constants.js'
+import { defaultAuthHeaders, YotoAPIError } from 'yoto-nodejs-client/lib/api-endpoints/helpers.js'
+
+/**
+ * @typedef {Object} LibraryCard
+ * @property {string} cardId
+ * @property {string} title
+ */
+
+/** Give up on a library request that takes longer than this */
+const LIBRARY_TIMEOUT_MS = 30_000
+
+/**
+ * Read `{ cards: [{ cardId, inFamilyLibrary, card: { title } }] }` from
+ * GET /card/family/library. Entries without an ID or title, marked as not in
+ * the library, or repeating a card already listed are skipped.
+ * @param {unknown} body
+ * @returns {LibraryCard[]}
+ */
+export function parseFamilyLibrary (body) {
+  const cards = body && typeof body === 'object' && 'cards' in body && Array.isArray(body.cards)
+    ? body.cards
+    : []
+
+  /** @type {Map<string, LibraryCard>} */
+  const byId = new Map()
+  for (const entry of cards) {
+    if (!entry || typeof entry !== 'object') continue
+    const record = /** @type {{ cardId?: unknown, inFamilyLibrary?: unknown, card?: { title?: unknown } }} */ (entry)
+    if (record.inFamilyLibrary === false) continue
+    const cardId = typeof record.cardId === 'string' ? record.cardId.trim() : ''
+    const title = typeof record.card?.title === 'string' ? record.card.title.trim() : ''
+    if (cardId && title && !byId.has(cardId)) byId.set(cardId, { cardId, title })
+  }
+  return [...byId.values()]
+}
+
+/**
+ * Fetch the family library (needs the `family:library:view` scope). It
+ * includes Make Your Own cards. yoto-nodejs-client has no method for this
+ * endpoint, so this uses its URL, headers and error type.
+ * @param {YotoClient} client
+ * @returns {Promise<LibraryCard[]>}
+ */
+export async function fetchFamilyLibrary (client) {
+  const accessToken = await client.token.getAccessToken()
+  const response = await fetch(new URL('/card/family/library', YOTO_API_URL), {
+    headers: defaultAuthHeaders({ accessToken }),
+    signal: AbortSignal.timeout(LIBRARY_TIMEOUT_MS),
+  })
+  if (!response.ok) {
+    const textBody = await response.text()
+    let jsonBody = null
+    try {
+      jsonBody = JSON.parse(textBody)
+    } catch {
+      jsonBody = null
+    }
+    // YotoAPIError only reads the status code from the response
+    const responseData = /** @type {ConstructorParameters<typeof YotoAPIError>[0]} */ (/** @type {unknown} */ ({ statusCode: response.status }))
+    throw new YotoAPIError(responseData, textBody, jsonBody)
+  }
+  return parseFamilyLibrary(await response.json())
+}

package/lib/utils/sanitize-name.js

@@ -27,12 +27,31 @@
  *
  * Starts and ends with a letter or number. Exception: may end with a period.
  * May have the following special characters: -"',.#&.
- * Must not include emojis.
+ * Must not include emojis. At most 64 characters (HAP's string limit).
  *
  * @param {string} name - The name to sanitize
  * @returns {string} The HomeKit-sanitized version of the name
  */
 export function sanitizeName (name) {
+  const cleaned = cleanName(name
+    // Curly quotes (common in card titles) become their allowed straight forms.
+    .replace(/[\u2018\u2019]/g, "'")
+    .replace(/[\u201C\u201D]/g, '"'))
+  if (cleaned.length <= MAX_NAME_LENGTH) return cleaned
+
+  // Too long: cut at the last word break that fits, then tidy the end again
+  const cut = cleaned.slice(0, MAX_NAME_LENGTH + 1)
+  const lastSpace = cut.lastIndexOf(' ')
+  return cleanName(lastSpace > 0 ? cut.slice(0, lastSpace) : cleaned.slice(0, MAX_NAME_LENGTH))
+}
+
+const MAX_NAME_LENGTH = 64
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+function cleanName (name) {
   return name
     // Replace any disallowed char (including emojis) with a space.
     .replace(/[^\p{L}\p{N}\-"'.,#&\s]/gu, ' ')
@@ -42,8 +61,9 @@ export function sanitizeName (name) {
     .trim()
     // Strip any leading non-letter/number.
     .replace(/^[^\p{L}\p{N}]+/u, '')
+    // Strip trailing chars that aren't a letter/number/period, with any
+    // spaces before them (e.g. the " &" in "Tales &").
+    .replace(/[^\p{L}\p{N}.]+$/u, '')
     // Collapse two or more trailing periods into one.
     .replace(/\.{2,}$/g, '.')
-    // Remove any other trailing char that's not letter/number/period.
-    .replace(/[^\p{L}\p{N}.]$/u, '')
 }

package/lib/utils/sleep-timer.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Sleep timer slider helpers: each slider percent is a fixed
+ * number of minutes (1% = 1 minute by default).
+ */
+
+export const DEFAULT_SLEEP_TIMER_MINUTES_PER_PERCENT = 1
+export const MAX_SLEEP_TIMER_MINUTES_PER_PERCENT = 10
+/** Duration used when the timer is switched on without picking a time */
+export const DEFAULT_SLEEP_TIMER_MINUTES = 30
+
+/**
+ * Read a minutes-per-percent setting, falling back to the default.
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function getSleepTimerMinutesPerPercent (value) {
+  const minutes = typeof value === 'string' ? Number(value) : value
+  if (typeof minutes !== 'number' || !Number.isFinite(minutes) || minutes <= 0) {
+    return DEFAULT_SLEEP_TIMER_MINUTES_PER_PERCENT
+  }
+  return Math.min(minutes, MAX_SLEEP_TIMER_MINUTES_PER_PERCENT)
+}
+
+/**
+ * Slider percent for the time left, rounded up so the slider only reaches 0
+ * when the timer ends. Timers longer than the slider shows stay at 100.
+ * @param {number} remainingSeconds
+ * @param {number} minutesPerPercent
+ * @returns {number}
+ */
+export function sleepSecondsToPercent (remainingSeconds, minutesPerPercent) {
+  if (!Number.isFinite(remainingSeconds) || remainingSeconds <= 0) return 0
+  return Math.min(100, Math.ceil(remainingSeconds / (minutesPerPercent * 60)))
+}
+
+/**
+ * Timer length in seconds for a slider percent.
+ * @param {number} percent
+ * @param {number} minutesPerPercent
+ * @returns {number}
+ */
+export function sleepPercentToSeconds (percent, minutesPerPercent) {
+  const clamped = Number.isFinite(percent) ? Math.max(0, Math.min(Math.round(percent), 100)) : 0
+  return Math.round(clamped * minutesPerPercent * 60)
+}

package/lib/utils/token-client-id.js

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Read which OAuth client an access token was issued to.
+ */
+
+/**
+ * The `azp` (authorized party) claim of a Yoto access token: the client ID it
+ * was issued to. Refreshing must use that same client ID, or Yoto rejects the
+ * refresh token with invalid_grant. The signature isn't checked; this only
+ * picks which client ID to send.
+ * @param {unknown} accessToken
+ * @returns {string | undefined}
+ */
+export function getTokenClientId (accessToken) {
+  if (typeof accessToken !== 'string') return undefined
+  const payload = accessToken.split('.')[1]
+  if (!payload) return undefined
+  try {
+    const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'))
+    const azp = claims && typeof claims === 'object' ? claims.azp : undefined
+    return typeof azp === 'string' && azp.trim() ? azp.trim() : undefined
+  } catch {
+    return undefined
+  }
+}

package/lib/utils/token-config.js

@@ -57,3 +57,60 @@ export function applyTokenUpdate (configContents, update) {
   // Homebridge writes config.json with 4-space indentation
   return JSON.stringify(parsed, null, 4)
 }
+
+/**
+ * @typedef {Object} SavedTokens
+ * @property {string} accessToken
+ * @property {string} refreshToken
+ * @property {number} tokenExpiresAt
+ */
+
+/**
+ * Tokens in config.json that are newer than the ones Homebridge handed the plugin.
+ *
+ * Homebridge gives a child bridge the config it read when Homebridge started, and
+ * reuses it when the child bridge restarts after its process exits. After a token
+ * refresh that copy holds a refresh token Yoto has already rotated away, and using
+ * it again fails with invalid_grant. The file on disk has the current ones.
+ *
+ * @param {string} configContents - Raw config.json contents
+ * @param {Object} options
+ * @param {string} options.platform - Platform name to match (e.g. 'Yoto')
+ * @param {string} [options.bridgeUsername] - Child bridge username, to pick the block when there are several
+ * @param {unknown} options.refreshToken - Refresh token Homebridge passed in
+ * @param {unknown} options.tokenExpiresAt - Its expiry (ms)
+ * @returns {SavedTokens | null}
+ */
+export function findNewerSavedTokens (configContents, { platform, bridgeUsername, refreshToken, tokenExpiresAt }) {
+  /** @type {unknown} */
+  let parsed
+  try {
+    parsed = JSON.parse(configContents)
+  } catch {
+    return null
+  }
+  if (!parsed || typeof parsed !== 'object') return null
+  const platforms = /** @type {Record<string, unknown>} */ (parsed)['platforms']
+  if (!Array.isArray(platforms)) return null
+
+  /** @type {Record<string, unknown>[]} */
+  const candidates = platforms.filter(entry => entry && typeof entry === 'object' && entry.platform === platform)
+  const block = bridgeUsername
+    ? candidates.find(entry => {
+      const bridge = entry['_bridge']
+      return bridge && typeof bridge === 'object' && /** @type {Record<string, unknown>} */ (bridge)['username'] === bridgeUsername
+    })
+    : (candidates.length === 1 ? candidates[0] : undefined)
+  if (!block) return null
+
+  const savedAccess = block['accessToken']
+  const savedRefresh = block['refreshToken']
+  const savedExpiresAt = block['tokenExpiresAt']
+  if (typeof savedAccess !== 'string' || typeof savedRefresh !== 'string' || typeof savedExpiresAt !== 'number') return null
+  if (savedRefresh === refreshToken) return null
+
+  const currentExpiresAt = typeof tokenExpiresAt === 'number' ? tokenExpiresAt : 0
+  if (savedExpiresAt <= currentExpiresAt) return null
+
+  return { accessToken: savedAccess, refreshToken: savedRefresh, tokenExpiresAt: savedExpiresAt }
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@mdjhnson/homebridge-yoto",
   "displayName": "Homebridge Yoto",
   "description": "Control your Yoto players through Apple HomeKit with real-time MQTT updates",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "author": "mdjhnson (https://github.com/mdjhnson)",
   "contributors": [
     "Bret Comnes <bcomnes@gmail.com> (https://bret.io)"