yoto-nodejs-client 0.0.7 → 0.0.9

package/README.md

@@ -958,6 +958,7 @@ Create a stateful device client that manages device state primarily from MQTT wi
 - `await deviceClient.refreshConfig()` - Refresh config from HTTP API
 - `await deviceClient.updateConfig(configUpdate)` - Update device configuration
 - `await deviceClient.sendCommand(command)` - Send device command via HTTP
+- `await deviceClient.startCard({ cardId, [chapterKey], [trackKey] })` - Start playing a card
 
 **Events:**
 - `started(metadata)` - Device client started, passes metadata object with device, config, shortcuts, status, playback, initialized, running

package/lib/pkg.d.cts

@@ -7,13 +7,15 @@ export const pkg: {
         url: string;
     };
     dependencies: {
+        fastq: string;
         "jwt-decode": string;
         mqtt: string;
+        "quick-lru": string;
         undici: string;
     };
     devDependencies: {
-        "@unblessed/node": string;
         "@types/node": string;
+        "@unblessed/node": string;
         "@voxpelli/tsconfig": string;
         argsclopts: string;
         "auto-changelog": string;

package/lib/yoto-device.d.ts

@@ -116,6 +116,34 @@ export const YotoDeviceModelConfigType: {};
  * @property {string} updatedAt - ISO 8601 timestamp of last update
  */
 export const YotoPlaybackStateType: {};
+/**
+ * Cached chapter info for playback enrichment.
+ * @typedef {Object} YotoCardCacheChapterInfo
+ * @property {string} key
+ * @property {string} title
+ */
+/**
+ * Cached track info for playback enrichment.
+ * @typedef {Object} YotoCardCacheTrackInfo
+ * @property {string} key
+ * @property {string} title
+ * @property {number} duration
+ * @property {string} chapterKey
+ * @property {string} chapterTitle
+ */
+/**
+ * Cached card metadata for playback enrichment.
+ * @typedef {Object} YotoCardCacheEntry
+ * @property {string} cardId
+ * @property {string} title
+ * @property {Map<string, YotoCardCacheChapterInfo>} chaptersByKey
+ * @property {Map<string, YotoCardCacheTrackInfo>} tracksByKey
+ */
+/**
+ * Cached card lookup task.
+ * @typedef {Object} YotoCardCacheTask
+ * @property {string} cardId
+ */
 /**
  * Complete device client state
  * @typedef {Object} YotoDeviceClientState
@@ -389,23 +417,10 @@ export class YotoDeviceModel extends EventEmitter<YotoDeviceModelEventMap> {
     reboot(): Promise<void>;
     /**
      * Start card playback over MQTT
-     * @param {Object} options - Card start options
-     * @param {string} options.uri - Card URI (e.g., "https://yoto.io/<cardID>")
-     * @param {string} [options.chapterKey] - Chapter to start from
-     * @param {string} [options.trackKey] - Track to start from
-     * @param {number} [options.secondsIn] - Playback start offset in seconds
-     * @param {number} [options.cutOff] - Playback stop offset in seconds
-     * @param {boolean} [options.anyButtonStop] - Whether button press stops playback
+     * @param {YotoCardStartOptions} options - Card start options
      * @returns {Promise<void>}
      */
-    startCard(options: {
-        uri: string;
-        chapterKey?: string | undefined;
-        trackKey?: string | undefined;
-        secondsIn?: number | undefined;
-        cutOff?: number | undefined;
-        anyButtonStop?: boolean | undefined;
-    }): Promise<void>;
+    startCard(options: YotoCardStartOptions): Promise<void>;
     /**
      * Stop card playback over MQTT
      * @returns {Promise<void>}
@@ -522,6 +537,35 @@ export type DayMode = "unknown" | "night" | "day";
  * Power source state
  */
 export type PowerSource = "battery" | "dock" | "usb-c" | "wireless";
+/**
+ * Card start options for Yoto playback.
+ */
+export type YotoCardStartOptions = {
+    /**
+     * - Card ID (used when uri is not provided)
+     */
+    cardId: string;
+    /**
+     * - Chapter to start from
+     */
+    chapterKey?: string;
+    /**
+     * - Track to start from
+     */
+    trackKey?: string;
+    /**
+     * - Playback start offset in seconds
+     */
+    secondsIn?: number;
+    /**
+     * - Playback stop offset in seconds
+     */
+    cutOff?: number;
+    /**
+     * - Whether button press stops playback
+     */
+    anyButtonStop?: boolean;
+};
 /**
  * Canonical device status - normalized format for both HTTP and MQTT sources
  *
@@ -829,6 +873,38 @@ export type YotoPlaybackState = {
      */
     updatedAt: string;
 };
+/**
+ * Cached chapter info for playback enrichment.
+ */
+export type YotoCardCacheChapterInfo = {
+    key: string;
+    title: string;
+};
+/**
+ * Cached track info for playback enrichment.
+ */
+export type YotoCardCacheTrackInfo = {
+    key: string;
+    title: string;
+    duration: number;
+    chapterKey: string;
+    chapterTitle: string;
+};
+/**
+ * Cached card metadata for playback enrichment.
+ */
+export type YotoCardCacheEntry = {
+    cardId: string;
+    title: string;
+    chaptersByKey: Map<string, YotoCardCacheChapterInfo>;
+    tracksByKey: Map<string, YotoCardCacheTrackInfo>;
+};
+/**
+ * Cached card lookup task.
+ */
+export type YotoCardCacheTask = {
+    cardId: string;
+};
 /**
  * Complete device client state
  */

package/lib/yoto-device.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"yoto-device.d.ts","sourceRoot":"","sources":["yoto-device.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"yoto-device.d.ts","sourceRoot":"","sources":["yoto-device.js"],"names":[],"mappings":"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"}

package/lib/yoto-device.js

@@ -8,17 +8,26 @@
 
 /**
  * @import { IConnackPacket } from 'mqtt'
+ * @import { queueAsPromised } from 'fastq'
  * @import { YotoClient } from './api-client.js'
+ * @import { YotoCard } from './api-endpoints/content.js'
  * @import { YotoDevice, YotoDeviceConfig, YotoDeviceShortcuts, YotoDeviceFullStatus, YotoDeviceStatusResponse, YotoDeviceCommand, YotoDeviceCommandResponse } from './api-endpoints/devices.js'
  * @import { YotoMqttClient, YotoMqttStatus, YotoEventsMessage, YotoLegacyStatus, YotoStatusMessage, YotoStatusLegacyMessage, YotoResponseMessage, YotoMqttClientDisconnectMetadata, YotoMqttClientCloseMetadata, PlaybackStatus } from './mqtt/client.js'
  * @import { YotoMqttOptions } from './mqtt/factory.js'
+ * @import { YotoCardStartCommand } from './mqtt/commands.js'
  */
 
 import { EventEmitter } from 'events'
+import fastq from 'fastq'
+import QuickLRU from 'quick-lru'
 import { parseTemperature } from './helpers/temperature.js'
 import { detectPowerState } from './helpers/power-state.js'
 import { typedKeys } from './helpers/typed-keys.js'
 
+const CARD_CACHE_MAX_SIZE = 2000
+const CARD_CACHE_QUEUE_CONCURRENCY = 1
+const CARD_ID_NONE = 'none'
+
 // ============================================================================
 // Type Definitions
 // ============================================================================
@@ -81,6 +90,17 @@ function convertPowerSource (numericSource) {
  * @typedef {'battery' | 'dock' | 'usb-c' | 'wireless'} PowerSource
  */
 
+/**
+ * Card start options for Yoto playback.
+ * @typedef {Object} YotoCardStartOptions
+ * @property {string} cardId - Card ID (used when uri is not provided)
+ * @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 button press stops playback
+ */
+
 /**
  * Normalize "0"/"1" booleans from config to true/false.
  * @param {string | boolean} value
@@ -398,6 +418,38 @@ export const YotoPlaybackStateType = {}
 // Internal Types
 // ============================================================================
 
+/**
+ * Cached chapter info for playback enrichment.
+ * @typedef {Object} YotoCardCacheChapterInfo
+ * @property {string} key
+ * @property {string} title
+ */
+
+/**
+ * Cached track info for playback enrichment.
+ * @typedef {Object} YotoCardCacheTrackInfo
+ * @property {string} key
+ * @property {string} title
+ * @property {number} duration
+ * @property {string} chapterKey
+ * @property {string} chapterTitle
+ */
+
+/**
+ * Cached card metadata for playback enrichment.
+ * @typedef {Object} YotoCardCacheEntry
+ * @property {string} cardId
+ * @property {string} title
+ * @property {Map<string, YotoCardCacheChapterInfo>} chaptersByKey
+ * @property {Map<string, YotoCardCacheTrackInfo>} tracksByKey
+ */
+
+/**
+ * Cached card lookup task.
+ * @typedef {Object} YotoCardCacheTask
+ * @property {string} cardId
+ */
+
 /**
  * Complete device client state
  * @typedef {Object} YotoDeviceClientState
@@ -555,6 +607,9 @@ export class YotoDeviceModel extends EventEmitter {
   /** @type {NodeJS.Timeout | null} */ #eventsRequestTimer = null
   /** @type {NodeJS.Timeout | null} */ #backgroundPollTimer = null
   /** @type {number | null} */ #shutdownDetectedAt = null
+  /** @type {QuickLRU<string, YotoCardCacheEntry>} */ #cardCache = new QuickLRU({ maxSize: CARD_CACHE_MAX_SIZE })
+  /** @type {queueAsPromised<YotoCardCacheTask, YotoCardCacheEntry | null>} */ #cardCacheQueue = fastq.promise(this, this.#fetchCardCacheTask, CARD_CACHE_QUEUE_CONCURRENCY)
+  /** @type {Set<string>} */ #cardCacheQueueTasks = new Set()
 
   /**
    * Create a Yoto device client
@@ -941,17 +996,26 @@ export class YotoDeviceModel extends EventEmitter {
 
   /**
    * Start card playback over MQTT
-   * @param {Object} options - Card start options
-   * @param {string} options.uri - Card URI (e.g., "https://yoto.io/<cardID>")
-   * @param {string} [options.chapterKey] - Chapter to start from
-   * @param {string} [options.trackKey] - Track to start from
-   * @param {number} [options.secondsIn] - Playback start offset in seconds
-   * @param {number} [options.cutOff] - Playback stop offset in seconds
-   * @param {boolean} [options.anyButtonStop] - Whether button press stops playback
+   * @param {YotoCardStartOptions} options - Card start options
    * @returns {Promise<void>}
    */
   async startCard (options) {
-    return await this.#mqttClient?.startCard(options)
+    const uri = `https://yoto.io/${options.cardId}`
+
+    if (!uri) {
+      throw new Error('Card URI or cardId is required')
+    }
+
+    /** @type {YotoCardStartCommand} */
+    const payload = { uri }
+
+    if (typeof options.chapterKey === 'string') payload.chapterKey = options.chapterKey
+    if (typeof options.trackKey === 'string') payload.trackKey = options.trackKey
+    if (typeof options.secondsIn === 'number') payload.secondsIn = options.secondsIn
+    if (typeof options.cutOff === 'number') payload.cutOff = options.cutOff
+    if (typeof options.anyButtonStop === 'boolean') payload.anyButtonStop = options.anyButtonStop
+
+    return await this.#mqttClient?.startCard(payload)
   }
 
   /**
@@ -3081,6 +3145,69 @@ export class YotoDeviceModel extends EventEmitter {
     }
   }
 
+  /**
+   * Apply cached card metadata to playback state (if available).
+   * @param {string | null} cardId
+   * @param {YotoPlaybackState} playback
+   * @param {Set<keyof YotoPlaybackState>} playbackChangedFields
+   * @returns {boolean}
+   */
+  #applyCardCacheToPlayback (cardId, playback, playbackChangedFields) {
+    if (!isCacheableCardId(cardId)) {
+      return false
+    }
+
+    const cachedEntry = this.#cardCache.get(cardId)
+    if (cachedEntry) {
+      return applyCardCacheToPlayback(cachedEntry, playback, playbackChangedFields)
+    }
+
+    this.#queueCardCacheFetch(cardId)
+    return false
+  }
+
+  /**
+   * @param {YotoCardCacheTask} task
+   * @returns {Promise<YotoCardCacheEntry | null>}
+   */
+  async #fetchCardCacheTask (task) {
+    try {
+      const response = await this.#client.getContent({ cardId: task.cardId })
+      const entry = buildCardCacheEntry(response.card)
+      this.#cardCache.set(task.cardId, entry)
+
+      if (this.#state.playback.cardId === task.cardId) {
+        /** @type {Set<keyof YotoPlaybackState>} */
+        const playbackChangedFields = new Set()
+        if (applyCardCacheToPlayback(entry, this.#state.playback, playbackChangedFields)) {
+          this.#state.playback.updatedAt = new Date().toISOString()
+          this.#state.lastUpdate.playback = Date.now()
+          this.emit('playbackUpdate', this.playback, playbackChangedFields)
+        }
+      }
+
+      return entry
+    } catch {
+      return null
+    } finally {
+      this.#cardCacheQueueTasks.delete(task.cardId)
+    }
+  }
+
+  /**
+   * Fetch card content for playback enrichment and cache the result.
+   * @param {string} cardId
+   * @returns {void}
+   */
+  #queueCardCacheFetch (cardId) {
+    if (this.#cardCache.has(cardId) || this.#cardCacheQueueTasks.has(cardId)) {
+      return
+    }
+
+    this.#cardCacheQueueTasks.add(cardId)
+    this.#cardCacheQueue.push({ cardId })
+  }
+
   /**
    * Handle MQTT event message - updates status, config, and playback
    * Events are partial updates - only changed fields are included
@@ -3102,6 +3229,7 @@ export class YotoDeviceModel extends EventEmitter {
     let playbackChanged = false
 
     const { status, config, playback } = this.#state
+    const previousCardId = playback.cardId
     /** @type {Set<keyof YotoDeviceStatus>} */
     const statusChangedFields = new Set()
     /** @type {Set<keyof YotoDeviceModelConfig>} */
@@ -3183,10 +3311,13 @@ export class YotoDeviceModel extends EventEmitter {
           break
         }
         case 'cardId': {
-          if (eventsMessage.cardId !== undefined && playback.cardId !== eventsMessage.cardId) {
-            playback.cardId = eventsMessage.cardId
-            playbackChangedFields.add('cardId')
-            playbackChanged = true
+          if (eventsMessage.cardId !== undefined) {
+            const normalizedCardId = eventsMessage.cardId === CARD_ID_NONE ? null : eventsMessage.cardId
+            if (playback.cardId !== normalizedCardId) {
+              playback.cardId = normalizedCardId
+              playbackChangedFields.add('cardId')
+              playbackChanged = true
+            }
           }
           break
         }
@@ -3265,6 +3396,12 @@ export class YotoDeviceModel extends EventEmitter {
       handleField(key, eventsMessage)
     }
 
+    if (previousCardId !== playback.cardId) {
+      if (this.#applyCardCacheToPlayback(playback.cardId, playback, playbackChangedFields)) {
+        playbackChanged = true
+      }
+    }
+
     // Update timestamps and emit events for changed categories
     if (statusChanged) {
       this.#state.lastUpdate.status = Date.now()
@@ -3311,6 +3448,98 @@ function createEmptyPlaybackState () {
   }
 }
 
+/**
+ * @param {string | null} cardId
+ * @returns {cardId is string}
+ */
+function isCacheableCardId (cardId) {
+  return typeof cardId === 'string' && cardId.length > 0 && cardId !== CARD_ID_NONE
+}
+
+/**
+ * @param {YotoCard} card
+ * @returns {YotoCardCacheEntry}
+ */
+function buildCardCacheEntry (card) {
+  const chaptersByKey = new Map()
+  const tracksByKey = new Map()
+
+  for (const chapter of card.content.chapters) {
+    chaptersByKey.set(chapter.key, {
+      key: chapter.key,
+      title: chapter.title
+    })
+
+    for (const track of chapter.tracks) {
+      tracksByKey.set(track.key, {
+        key: track.key,
+        title: track.title,
+        duration: track.duration,
+        chapterKey: chapter.key,
+        chapterTitle: chapter.title
+      })
+    }
+  }
+
+  return {
+    cardId: card.cardId,
+    title: card.title,
+    chaptersByKey,
+    tracksByKey
+  }
+}
+
+/**
+ * @param {YotoCardCacheEntry} entry
+ * @param {YotoPlaybackState} playback
+ * @param {Set<keyof YotoPlaybackState>} changedFields
+ * @returns {boolean}
+ */
+function applyCardCacheToPlayback (entry, playback, changedFields) {
+  let changed = false
+  const { trackKey } = playback
+
+  if (trackKey) {
+    const trackInfo = entry.tracksByKey.get(trackKey)
+    if (trackInfo) {
+      if (playback.trackTitle !== trackInfo.title) {
+        playback.trackTitle = trackInfo.title
+        changedFields.add('trackTitle')
+        changed = true
+      }
+
+      if (playback.trackLength !== trackInfo.duration) {
+        playback.trackLength = trackInfo.duration
+        changedFields.add('trackLength')
+        changed = true
+      }
+
+      if (playback.chapterKey !== trackInfo.chapterKey) {
+        playback.chapterKey = trackInfo.chapterKey
+        changedFields.add('chapterKey')
+        changed = true
+      }
+
+      if (playback.chapterKey === trackInfo.chapterKey && playback.chapterTitle !== trackInfo.chapterTitle) {
+        playback.chapterTitle = trackInfo.chapterTitle
+        changedFields.add('chapterTitle')
+        changed = true
+      }
+    }
+  }
+
+  if (playback.chapterKey) {
+    const chapterInfo = entry.chaptersByKey.get(playback.chapterKey)
+    if (chapterInfo && playback.chapterTitle !== chapterInfo.title) {
+      playback.chapterTitle = chapterInfo.title
+      changedFields.add('chapterTitle')
+      changed = true
+    }
+  }
+
+  return changed
+}
+
 /**
  * Create an empty device config object
  * @returns {YotoDeviceModelConfig}

package/lib/yoto-device.test.js

@@ -1,4 +1,5 @@
 /** @import { YotoDevice } from './api-endpoints/devices.js' */
+/** @import { YotoPlaybackState } from './yoto-device.js' */
 
 import test from 'node:test'
 import assert from 'node:assert/strict'
@@ -15,6 +16,122 @@ import {
 } from './test-helpers/device-model-test-helpers.js'
 
 const envPath = join(import.meta.dirname, '..', '.env')
+const PLAYBACK_SAMPLE_SCAN_LIMIT = 5
+
+/**
+ * @typedef {Object} PlaybackSample
+ * @property {string} cardId
+ * @property {Map<string, { title: string, duration: number, chapterKey: string, chapterTitle: string }>} tracksByKey
+ * @property {string} chapterKey
+ * @property {string} chapterTitle
+ * @property {string} trackKey
+ * @property {string} trackTitle
+ * @property {number} trackLength
+ */
+
+/**
+ * @param {YotoDeviceModel} model
+ * @param {(playback: YotoPlaybackState, changedFields: Set<keyof YotoPlaybackState>) => boolean} predicate
+ * @param {number} timeoutMs
+ * @param {string} label
+ * @returns {Promise<[YotoPlaybackState, Set<keyof YotoPlaybackState>]>}
+ */
+function waitForPlaybackUpdateMatching (model, predicate, timeoutMs, label) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      model.off('playbackUpdate', handler)
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+
+    /**
+     * @param {YotoPlaybackState} playback
+     * @param {Set<keyof YotoPlaybackState>} changedFields
+     */
+    const handler = (playback, changedFields) => {
+      let matches = false
+
+      try {
+        matches = predicate(playback, changedFields)
+      } catch (err) {
+        clearTimeout(timeout)
+        model.off('playbackUpdate', handler)
+        reject(err)
+        return
+      }
+
+      if (!matches) {
+        return
+      }
+
+      clearTimeout(timeout)
+      model.off('playbackUpdate', handler)
+      resolve([playback, changedFields])
+    }
+
+    model.on('playbackUpdate', handler)
+  })
+}
+
+/**
+ * @param {YotoClient} client
+ * @returns {Promise<PlaybackSample | null>}
+ */
+async function findPlaybackSample (client) {
+  const response = await client.getUserMyoContent({ showDeleted: false })
+
+  for (const card of response.cards.slice(0, PLAYBACK_SAMPLE_SCAN_LIMIT)) {
+    if (!card.cardId || card.deleted) {
+      continue
+    }
+
+    try {
+      const contentResponse = await client.getContent({ cardId: card.cardId })
+      const chapters = contentResponse.card.content.chapters
+      const firstChapter = chapters.find(candidate => candidate.tracks.length > 0)
+
+      if (!firstChapter) {
+        continue
+      }
+
+      const firstTrack = firstChapter.tracks[0]
+
+      if (!firstTrack || typeof firstTrack.title !== 'string' || !Number.isFinite(firstTrack.duration)) {
+        continue
+      }
+
+      const tracksByKey = new Map()
+
+      for (const chapter of chapters) {
+        for (const track of chapter.tracks) {
+          if (!track || typeof track.title !== 'string' || !Number.isFinite(track.duration)) {
+            continue
+          }
+
+          tracksByKey.set(track.key, {
+            title: track.title,
+            duration: track.duration,
+            chapterKey: chapter.key,
+            chapterTitle: chapter.title
+          })
+        }
+      }
+
+      return {
+        cardId: contentResponse.card.cardId,
+        tracksByKey,
+        chapterKey: firstChapter.key,
+        chapterTitle: firstChapter.title,
+        trackKey: firstTrack.key,
+        trackTitle: firstTrack.title,
+        trackLength: firstTrack.duration
+      }
+    } catch {
+      continue
+    }
+  }
+
+  return null
+}
 
 /**
  * @returns {YotoClient}
@@ -86,3 +203,104 @@ test('YotoDeviceModel - online devices', async (t) => {
     await assertDeviceModel(client, onlineV3)
   })
 })
+
+test('YotoDeviceModel - playback normalization', async (t) => {
+  loadTestTokens()
+  const client = createTestClient()
+  const response = await client.getDevices()
+
+  const onlineDevice = response.devices.find(device => device.online)
+  if (!onlineDevice) {
+    t.skip('No online device found')
+    return
+  }
+
+  const sample = await findPlaybackSample(client)
+  if (!sample) {
+    t.skip('No MYO content with tracks available')
+    return
+  }
+
+  const model = new YotoDeviceModel(client, onlineDevice)
+
+  try {
+    await waitForModelReady(model)
+    assertPlaybackShape(model.playback)
+
+    const mqttClient = model.mqttClient
+    assert.ok(mqttClient, 'MQTT client should be initialized')
+
+    await t.test('card cache enrichment', async () => {
+      if (model.playback.cardId === sample.cardId) {
+        const resetPromise = waitForPlaybackUpdateMatching(
+          model,
+          (playback, changedFields) => playback.cardId === null && changedFields.has('cardId'),
+          5000,
+          'playback card reset'
+        )
+
+        mqttClient.emit('events', 'test', { cardId: 'none' })
+        await resetPromise
+      }
+
+      const cardUpdatePromise = waitForPlaybackUpdateMatching(
+        model,
+        (playback, changedFields) => playback.cardId === sample.cardId && changedFields.has('cardId'),
+        5000,
+        'playback card update'
+      )
+
+      const cacheUpdatePromise = waitForPlaybackUpdateMatching(
+        model,
+        (playback, changedFields) => {
+          if (playback.cardId !== sample.cardId) {
+            return false
+          }
+
+          return (
+            changedFields.has('trackTitle') ||
+            changedFields.has('trackLength') ||
+            changedFields.has('chapterKey') ||
+            changedFields.has('chapterTitle')
+          )
+        },
+        15000,
+        'playback cache update'
+      )
+
+      mqttClient.emit('events', 'test', {
+        cardId: sample.cardId,
+        trackKey: sample.trackKey
+      })
+
+      const [cardPlayback] = await cardUpdatePromise
+      assert.equal(cardPlayback.cardId, sample.cardId)
+
+      const [cachePlayback] = await cacheUpdatePromise
+      assert.ok(cachePlayback.trackKey, 'trackKey should be set after cache update')
+      const trackInfo = sample.tracksByKey.get(cachePlayback.trackKey)
+      assert.ok(trackInfo, 'trackKey should exist in card content')
+      assert.equal(cachePlayback.trackTitle, trackInfo.title)
+      assert.equal(cachePlayback.trackLength, trackInfo.duration)
+      assert.equal(cachePlayback.chapterKey, trackInfo.chapterKey)
+      assert.equal(cachePlayback.chapterTitle, trackInfo.chapterTitle)
+    })
+
+    await t.test('cardId none normalization', async () => {
+      const noneUpdatePromise = waitForPlaybackUpdateMatching(
+        model,
+        (playback, changedFields) => playback.cardId === null && changedFields.has('cardId'),
+        5000,
+        'playback cardId none normalization'
+      )
+
+      mqttClient.emit('events', 'test', { cardId: 'none' })
+
+      const [nonePlayback, changedFields] = await noneUpdatePromise
+      assert.equal(nonePlayback.cardId, null)
+      assert.ok(changedFields.has('cardId'), 'cardId should be in changed fields')
+    })
+  } finally {
+    await model.stop()
+  }
+})

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "yoto-nodejs-client",
   "description": "(Unofficial) Node.js client for the Yoto API with automatic token refresh, MQTT device communication, and TypeScript support",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "author": "Bret Comnes <bcomnes@gmail.com> (https://bret.io)",
   "bugs": {
     "url": "https://github.com/bcomnes/yoto-nodejs-client/issues"
   },
   "dependencies": {
+    "fastq": "^1.20.1",
     "jwt-decode": "^4.0.0",
     "mqtt": "^5.14.1",
+    "quick-lru": "^7.3.0",
     "undici": "^7.16.0"
   },
   "devDependencies": {
-    "@unblessed/node": "1.0.0-alpha.23",
     "@types/node": "^25.0.0",
+    "@unblessed/node": "1.0.0-alpha.23",
     "@voxpelli/tsconfig": "^16.1.0",
     "argsclopts": "^1.0.5",
     "auto-changelog": "^2.0.0",