yoto-nodejs-client 0.0.6 → 0.0.8

package/README.md

@@ -211,24 +211,21 @@ account.on('started', (metadata) => {
 
 
 
-// Listen for device-specific events from individual devices
-account.on('deviceAdded', (deviceId, deviceModel) => {
-  // Attach event listeners to each device as it's added
-  deviceModel.on('statusUpdate', (status, source) => {
-    console.log(`${deviceId} battery: ${status.batteryLevelPercentage}%`)
-  })
+// Listen for device events across all devices via the unified bus
+account.on('statusUpdate', ({ deviceId, status, source }) => {
+  console.log(`${deviceId} battery: ${status.batteryLevelPercentage}% (${source})`)
+})
 
-  deviceModel.on('online', (metadata) => {
-    console.log(`${deviceId} came online`)
-  })
+account.on('online', ({ deviceId }) => {
+  console.log(`${deviceId} came online`)
+})
 
-  deviceModel.on('offline', (metadata) => {
-    console.log(`${deviceId} went offline`)
-  })
+account.on('offline', ({ deviceId }) => {
+  console.log(`${deviceId} went offline`)
 })
 
 // Unified error handling
-account.on('error', (error, context) => {
+account.on('error', ({ error, context }) => {
   console.error(`Error in ${context.source}:`, error.message)
   if (context.deviceId) {
     console.error(`Device: ${context.deviceId}`)
@@ -961,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
@@ -970,10 +968,17 @@ Create a stateful device client that manages device state primarily from MQTT wi
 - `playbackUpdate(playback, changedFields)` - Playback state changed, passes (playback, changedFields)
 - `online(metadata)` - Device came online, passes metadata with reason and optional upTime
 - `offline(metadata)` - Device went offline, passes metadata with reason and optional shutDownReason or timeSinceLastSeen
-- `mqttConnect()` - MQTT client connected
+- `mqttConnect(metadata)` - MQTT client connected, passes CONNACK metadata
 - `mqttDisconnect(metadata)` - MQTT disconnect packet received, passes metadata with disconnect packet
 - `mqttClose(metadata)` - MQTT connection closed, passes metadata with close reason
 - `mqttReconnect()` - MQTT client is reconnecting
+- `mqttOffline()` - MQTT client goes offline
+- `mqttEnd()` - MQTT client end is called
+- `mqttStatus(topic, message)` - Raw MQTT status messages (documented status topic)
+- `mqttEvents(topic, message)` - Raw MQTT events messages
+- `mqttStatusLegacy(topic, message)` - Raw legacy MQTT status messages (undocumented status topic)
+- `mqttResponse(topic, message)` - Raw MQTT response messages
+- `mqttUnknown(topic, message)` - Raw MQTT messages that do not match known types
 - `error(error)` - Error occurred, passes error
 
 **Static Properties & Methods:**
@@ -1051,11 +1056,27 @@ Create an account manager that automatically discovers and manages all devices f
 **Events:**
 - `started(metadata)` - Account started (metadata: { deviceCount, devices })
 - `stopped()` - Account stopped
-- `deviceAdded(deviceId, deviceModel)` - Device was added
-- `deviceRemoved(deviceId)` - Device was removed
-- `error(error, context)` - Error occurred (context: { source, deviceId, operation })
-
-**Note:** To listen to individual device events (statusUpdate, configUpdate, playbackUpdate, online, offline, mqttConnect, mqttDisconnect, mqttClose, mqttReconnect, etc.), access the device models directly via `account.devices` or `account.getDevice(deviceId)` and attach listeners to them.
+- `deviceAdded({ deviceId })` - Device was added
+- `deviceRemoved({ deviceId })` - Device was removed
+- `statusUpdate({ deviceId, status, source, changedFields })` - Re-emitted device status update
+- `configUpdate({ deviceId, config, changedFields })` - Re-emitted config update
+- `playbackUpdate({ deviceId, playback, changedFields })` - Re-emitted playback update
+- `online({ deviceId, metadata })` - Re-emitted online event
+- `offline({ deviceId, metadata })` - Re-emitted offline event
+- `mqttConnect({ deviceId, metadata })` - Re-emitted MQTT connect
+- `mqttDisconnect({ deviceId, metadata })` - Re-emitted MQTT disconnect
+- `mqttClose({ deviceId, metadata })` - Re-emitted MQTT close
+- `mqttReconnect({ deviceId })` - Re-emitted MQTT reconnect
+- `mqttOffline({ deviceId })` - Re-emitted MQTT offline
+- `mqttEnd({ deviceId })` - Re-emitted MQTT end
+- `mqttStatus({ deviceId, topic, message })` - Re-emitted raw MQTT status
+- `mqttEvents({ deviceId, topic, message })` - Re-emitted raw MQTT events
+- `mqttStatusLegacy({ deviceId, topic, message })` - Re-emitted raw MQTT legacy status
+- `mqttResponse({ deviceId, topic, message })` - Re-emitted raw MQTT response
+- `mqttUnknown({ deviceId, topic, message })` - Re-emitted raw MQTT unknown message
+- `error({ error, context })` - Error occurred (context: { source, deviceId, operation })
+
+**Note:** You can still listen to individual device events by attaching listeners to each `YotoDeviceModel`, but the account now re-emits device and MQTT events with device context for unified handling.
 
 ```js
 import { YotoAccount } from 'yoto-nodejs-client'
@@ -1075,26 +1096,21 @@ const account = new YotoAccount({
 })
 
 // Account-level error handling
-account.on('error', (error, context) => {
+account.on('error', ({ error, context }) => {
   console.error(`Error in ${context.source}:`, error.message)
 })
 
-// Listen to device added events
-account.on('deviceAdded', (deviceId, deviceModel) => {
-  console.log(`Device ${deviceId} added`)
-  
-  // Attach listeners to individual devices
-  deviceModel.on('statusUpdate', (status, source) => {
-    console.log(`${deviceId} battery: ${status.batteryLevelPercentage}%`)
-  })
-  
-  deviceModel.on('online', (metadata) => {
-    console.log(`${deviceId} came online (${metadata.reason})`)
-  })
-  
-  deviceModel.on('offline', (metadata) => {
-    console.log(`${deviceId} went offline (${metadata.reason})`)
-  })
+// Unified device events across all devices
+account.on('statusUpdate', ({ deviceId, status, source }) => {
+  console.log(`${deviceId} battery: ${status.batteryLevelPercentage}% (${source})`)
+})
+
+account.on('online', ({ deviceId, metadata }) => {
+  console.log(`${deviceId} came online (${metadata.reason})`)
+})
+
+account.on('offline', ({ deviceId, metadata }) => {
+  console.log(`${deviceId} went offline (${metadata.reason})`)
 })
 
 await account.start()

package/lib/test-helpers/device-model-test-helpers.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @param {Promise<unknown>} promise
+ * @param {number} timeoutMs
+ * @param {string} label
+ * @returns {Promise<unknown>}
+ */
+export function withTimeout(promise: Promise<unknown>, timeoutMs: number, label: string): Promise<unknown>;
+/**
+ * @param {YotoDeviceModel} model
+ * @returns {Promise<void>}
+ */
+export function waitForModelReady(model: YotoDeviceModel): Promise<void>;
+/**
+ * @param {YotoDeviceModelConfig} config
+ */
+export function assertConfigShape(config: YotoDeviceModelConfig): void;
+/**
+ * @param {YotoPlaybackState} playback
+ */
+export function assertPlaybackShape(playback: YotoPlaybackState): void;
+/**
+ * @param {string | undefined} value
+ * @returns {string}
+ */
+export function toLower(value: string | undefined): string;
+import type { YotoDeviceModel } from '../yoto-device.js';
+import type { YotoDeviceModelConfig } from '../yoto-device.js';
+import type { YotoPlaybackState } from '../yoto-device.js';
+//# sourceMappingURL=device-model-test-helpers.d.ts.map

package/lib/test-helpers/device-model-test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-model-test-helpers.d.ts","sourceRoot":"","sources":["device-model-test-helpers.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,qCALW,OAAO,CAAC,OAAO,CAAC,aAChB,MAAM,SACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAS5B;AAED;;;GAGG;AACH,yCAHW,eAAe,GACb,OAAO,CAAC,IAAI,CAAC,CAUzB;AAED;;GAEG;AACH,0CAFW,qBAAqB,QAkD/B;AAED;;GAEG;AACH,8CAFW,iBAAiB,QAkB3B;AAED;;;GAGG;AACH,+BAHW,MAAM,GAAG,SAAS,GAChB,MAAM,CAIlB;qCAnH8E,mBAAmB;2CAAnB,mBAAmB;uCAAnB,mBAAmB"}

package/lib/test-helpers/device-model-test-helpers.js

@@ -0,0 +1,116 @@
+/** @import { YotoDeviceModel, YotoDeviceModelConfig, YotoPlaybackState } from '../yoto-device.js' */
+
+import assert from 'node:assert/strict'
+import { once } from 'node:events'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+/**
+ * @param {Promise<unknown>} promise
+ * @param {number} timeoutMs
+ * @param {string} label
+ * @returns {Promise<unknown>}
+ */
+export function withTimeout (promise, timeoutMs, label) {
+  return Promise.race([
+    promise,
+    sleep(timeoutMs).then(() => {
+      throw new Error(`${label} timed out after ${timeoutMs}ms`)
+    })
+  ])
+}
+
+/**
+ * @param {YotoDeviceModel} model
+ * @returns {Promise<void>}
+ */
+export async function waitForModelReady (model) {
+  const started = withTimeout(once(model, 'started'), 15000, 'started')
+  const statusUpdated = withTimeout(once(model, 'statusUpdate'), 15000, 'statusUpdate')
+  const configUpdated = withTimeout(once(model, 'configUpdate'), 15000, 'configUpdate')
+
+  await model.start()
+  await Promise.all([started, statusUpdated, configUpdated])
+  await sleep(1500)
+}
+
+/**
+ * @param {YotoDeviceModelConfig} config
+ */
+export function assertConfigShape (config) {
+  assert.ok(Array.isArray(config.alarms), 'alarms should be an array')
+  assert.equal(typeof config.ambientColour, 'string', 'ambientColour should be string')
+  assert.equal(typeof config.bluetoothEnabled, 'boolean', 'bluetoothEnabled should be boolean')
+  assert.equal(typeof config.btHeadphonesEnabled, 'boolean', 'btHeadphonesEnabled should be boolean')
+  assert.equal(typeof config.clockFace, 'string', 'clockFace should be string')
+  assert.equal(typeof config.dayDisplayBrightnessAuto, 'boolean', 'dayDisplayBrightnessAuto should be boolean')
+  if (config.dayDisplayBrightnessAuto) {
+    assert.equal(config.dayDisplayBrightness, null, 'dayDisplayBrightness should be null when auto')
+  } else {
+    assert.equal(typeof config.dayDisplayBrightness, 'number', 'dayDisplayBrightness should be number when not auto')
+  }
+  assert.equal(typeof config.dayTime, 'string', 'dayTime should be string')
+  assert.equal(typeof config.dayYotoDaily, 'string', 'dayYotoDaily should be string')
+  assert.equal(typeof config.dayYotoRadio, 'string', 'dayYotoRadio should be string')
+  assert.equal(typeof config.daySoundsOff, 'boolean', 'daySoundsOff should be boolean')
+  assert.equal(typeof config.displayDimBrightness, 'number', 'displayDimBrightness should be number')
+  assert.equal(typeof config.displayDimTimeout, 'number', 'displayDimTimeout should be number')
+  assert.equal(typeof config.headphonesVolumeLimited, 'boolean', 'headphonesVolumeLimited should be boolean')
+  assert.ok(config.hourFormat === 12 || config.hourFormat === 24, 'hourFormat should be 12 or 24')
+  assert.equal(typeof config.locale, 'string', 'locale should be string')
+  assert.equal(typeof config.logLevel, 'string', 'logLevel should be string')
+  assert.equal(typeof config.maxVolumeLimit, 'number', 'maxVolumeLimit should be number')
+  assert.equal(typeof config.nightAmbientColour, 'string', 'nightAmbientColour should be string')
+  assert.equal(typeof config.nightDisplayBrightnessAuto, 'boolean', 'nightDisplayBrightnessAuto should be boolean')
+  if (config.nightDisplayBrightnessAuto) {
+    assert.equal(config.nightDisplayBrightness, null, 'nightDisplayBrightness should be null when auto')
+  } else {
+    assert.equal(typeof config.nightDisplayBrightness, 'number', 'nightDisplayBrightness should be number when not auto')
+  }
+  assert.equal(typeof config.nightMaxVolumeLimit, 'number', 'nightMaxVolumeLimit should be number')
+  assert.equal(typeof config.nightTime, 'string', 'nightTime should be string')
+  assert.equal(typeof config.nightYotoDaily, 'string', 'nightYotoDaily should be string')
+  assert.equal(typeof config.nightYotoRadioEnabled, 'boolean', 'nightYotoRadioEnabled should be boolean')
+  if (config.nightYotoRadioEnabled) {
+    assert.equal(typeof config.nightYotoRadio, 'string', 'nightYotoRadio should be string when enabled')
+  } else {
+    assert.equal(config.nightYotoRadio, null, 'nightYotoRadio should be null when disabled')
+  }
+  assert.equal(typeof config.nightSoundsOff, 'boolean', 'nightSoundsOff should be boolean')
+  assert.equal(typeof config.pausePowerButton, 'boolean', 'pausePowerButton should be boolean')
+  assert.equal(typeof config.pauseVolumeDown, 'boolean', 'pauseVolumeDown should be boolean')
+  assert.equal(typeof config.repeatAll, 'boolean', 'repeatAll should be boolean')
+  assert.equal(typeof config.showDiagnostics, 'boolean', 'showDiagnostics should be boolean')
+  assert.equal(typeof config.shutdownTimeout, 'number', 'shutdownTimeout should be number')
+  assert.equal(typeof config.systemVolume, 'number', 'systemVolume should be number')
+  assert.equal(typeof config.timezone, 'string', 'timezone should be string')
+  assert.equal(typeof config.volumeLevel, 'string', 'volumeLevel should be string')
+}
+
+/**
+ * @param {YotoPlaybackState} playback
+ */
+export function assertPlaybackShape (playback) {
+  assert.ok(playback, 'playback should exist')
+  assert.equal(typeof playback.updatedAt, 'string', 'playback.updatedAt should be string')
+
+  assert.ok(playback.cardId === null || typeof playback.cardId === 'string', 'playback.cardId should be string or null')
+  assert.ok(playback.source === null || typeof playback.source === 'string', 'playback.source should be string or null')
+  assert.ok(playback.playbackStatus === null || typeof playback.playbackStatus === 'string', 'playback.playbackStatus should be string or null')
+  assert.ok(playback.trackTitle === null || typeof playback.trackTitle === 'string', 'playback.trackTitle should be string or null')
+  assert.ok(playback.trackKey === null || typeof playback.trackKey === 'string', 'playback.trackKey should be string or null')
+  assert.ok(playback.chapterTitle === null || typeof playback.chapterTitle === 'string', 'playback.chapterTitle should be string or null')
+  assert.ok(playback.chapterKey === null || typeof playback.chapterKey === 'string', 'playback.chapterKey should be string or null')
+  assert.ok(playback.position === null || typeof playback.position === 'number', 'playback.position should be number or null')
+  assert.ok(playback.trackLength === null || typeof playback.trackLength === 'number', 'playback.trackLength should be number or null')
+  assert.ok(playback.streaming === null || typeof playback.streaming === 'boolean', 'playback.streaming should be boolean or null')
+  assert.ok(playback.sleepTimerActive === null || typeof playback.sleepTimerActive === 'boolean', 'playback.sleepTimerActive should be boolean or null')
+  assert.ok(playback.sleepTimerSeconds === null || typeof playback.sleepTimerSeconds === 'number', 'playback.sleepTimerSeconds should be number or null')
+}
+
+/**
+ * @param {string | undefined} value
+ * @returns {string}
+ */
+export function toLower (value) {
+  return typeof value === 'string' ? value.toLowerCase() : ''
+}