yoto-nodejs-client 0.0.1 → 0.0.3

package/lib/mqtt/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["client.js"],"names":[],"mappings":"AAgIA;IAQE,wBALW,UAAU,YACV,MAAM,YAEd;QAA0B,aAAa;KACzC,EAaA;IATC,uBAA4B;IAC5B,iBAAwB;IACxB,uBAAoD;IAMpD;;;;;;;;;;MAAwB;IAO1B,aAFa,uBAAuB,CAMnC;IAMD,iBAFa,OAAO,CAInB;IA2GD,WAFa,OAAO,CAAC,IAAI,CAAC,CA8BzB;IAMD,cAFa,OAAO,CAAC,IAAI,CAAC,CAiBzB;IA4BD,iBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAMD,iBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAOD,kBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAMzB;IASD,cALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAMzB;IAOD,wBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAMzB;IAOD,uBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAMzB;IAMD,UAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAaD,mBARG;QAAwB,GAAG,EAAnB,MAAM;QACW,UAAU;QACV,QAAQ;QACR,SAAS;QACT,MAAM;QACL,aAAa;KACvC,GAAU,OAAO,CAAC,IAAI,CAAC,CAMzB;IAMD,YAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAMD,aAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAMD,cAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAYD,sBAPG;QAAyB,MAAM;QACI,IAAI;QACd,IAAI;QACJ,IAAI;QACJ,GAAG;KAC5B,GAAU,OAAO,CAAC,IAAI,CAAC,CAMzB;IAMD,gBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAMD,wBAFa,OAAO,CAAC,IAAI,CAAC,CAMzB;IAMD,4BAFa,OAAO,CAAC,IAAI,CAAC,CAMzB;IAMD,wBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAMD,oBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAMD,uBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAMD,qBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAUD,wBALG;QAAwB,GAAG,EAAnB,MAAM;QACU,OAAO,EAAvB,MAAM;QACW,QAAQ,EAAzB,OAAO;KACf,GAAU,OAAO,CAAC,IAAI,CAAC,CAMzB;;CACF;;gBAzhBa,OAAO;gBACP,OAAO;aACP,MAAM;gBACN,MAAM;mBACN,OAAO;uBACP,OAAO;eACP,MAAM;kBACN,MAAM;eACN,MAAM;aACN,MAAM;aACN,MAAM;oBACN,MAAM;mBACN,MAAM;iBACN,MAAM;iBACN,MAAM;eACN,MAAM;qBACN,MAAM;wBACN,MAAM;;;mBAON,MAAM;eACN,MAAM;iBACN,MAAM;kBACN,MAAM;SACN,MAAM;cACN,MAAM;qBACN,MAAM;iBACN,MAAM;cACN,MAAM;gBACN,MAAM;kBACN,MAAM;mBACN,MAAM;gBACN,OAAO;oBACP,MAAM;eACN,MAAM;iBACN,MAAM;iBACN,OAAO;YACP,MAAM;gBACN,MAAM;gBACN,IAAI,GAAG,IAAI;oBACX,MAAM;UACN,MAAM;SACN,MAAM;;;YAQjB;QAAkC,MAAM;QACN,QAAQ;QACR,IAAI;QACJ,MAAM;QACN,MAAM;QACN,SAAS;QACT,OAAO;QACP,MAAM;QACd,QAAQ,EAAvB,MAAM;QACgB,UAAU,EAAhC,IAAI,GAAG,MAAM;KAE1B;;sCAIY,cAAc,GAAG,WAAW,GAAG,cAAc;6BAG7B,QAAQ;gCAhFN,MAAM"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["client.js"],"names":[],"mappings":"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"}

package/lib/mqtt/client.js

@@ -20,8 +20,8 @@
  * @typedef {Object} YotoEventsMessage
  * @property {boolean} [repeatAll] - Repeat all tracks
  * @property {boolean} [streaming] - Whether streaming
- * @property {number} [volume] - Current volume level
- * @property {number} [volumeMax] - Maximum volume level
+ * @property {number} [volume] - Current user volume level (0-16 scale, maps to userVolumePercentage in status)
+ * @property {number} [volumeMax] - Maximum volume limit (0-16 scale, maps to systemVolumePercentage in status)
  * @property {boolean} [playbackWait] - Playback waiting
  * @property {boolean} [sleepTimerActive] - Sleep timer active
  * @property {number} [eventUtc] - Unix timestamp
@@ -34,37 +34,52 @@
  * @property {string} [chapterKey] - Current chapter key
  * @property {string} [trackTitle] - Current track title
  * @property {string} [trackKey] - Current track key
- * @property {string} [playbackStatus] - Playback status (e.g., "playing", "paused", "stopped")
+ * @property {'playing' | 'paused' | 'stopped' | 'loading' | string} [playbackStatus] - Playback status
  * @property {number} [sleepTimerSeconds] - Seconds remaining on sleep timer
  */
 
 /**
- * Status message from device
+ * Status message from device (MQTT /data/status)
+ *
+ * Device automatically publishes status updates every 5 minutes (matching keepalive interval).
+ * Can also be requested on-demand via requestStatus().
+ *
+ * Note: MQTT types differ from HTTP - uses booleans, non-nullable fields
  * @see https://yoto.dev/players-mqtt/mqtt-docs/#deviceiddatastatus
  * @typedef {Object} YotoStatusMessage
+ * @property {YotoMqttStatus} status - Status object
+ */
+
+/**
+ * MQTT status payload structure (documented spec)
+ *
+ * Automatic updates (every 5 minutes): 21 fields (excludes nightlightMode and temp)
+ * Requested status: All 23 fields including nightlightMode and temp
+ *
+ * @typedef {Object} YotoMqttStatus
  * @property {number} statusVersion - Status message version
  * @property {string} fwVersion - Firmware version
  * @property {string} productType - Product type identifier
  * @property {number} batteryLevel - Battery level percentage
  * @property {number} als - Ambient light sensor reading
- * @property {number} freeDisk - Free disk space
+ * @property {number} freeDisk - Free disk space in bytes
  * @property {number} shutdownTimeout - Shutdown timeout in seconds
  * @property {number} dbatTimeout - DBAT timeout
  * @property {number} charging - Charging state (0 or 1)
- * @property {string} activeCard - Active card ID
- * @property {number} cardInserted - Card insertion state
+ * @property {string} activeCard - Active card ID or 'none'
+ * @property {0 | 1 | 2} cardInserted - Card insertion state (0=none, 1=physical, 2=remote)
  * @property {number} playingStatus - Playing status code
  * @property {boolean} headphones - Headphones connected
  * @property {number} dnowBrightness - Current display brightness
  * @property {number} dayBright - Day brightness setting
  * @property {number} nightBright - Night brightness setting
  * @property {boolean} bluetoothHp - Bluetooth headphones enabled
- * @property {number} volume - Current volume
- * @property {number} userVolume - User volume setting
+ * @property {number} volume - System/max volume level (0-100 percentage, represents 0-16 hardware scale, maps to volumeMax in events)
+ * @property {number} userVolume - User volume setting (0-100 percentage, represents 0-16 hardware scale, maps to volume in events)
  * @property {'12' | '24'} timeFormat - Time format preference
- * @property {string} nightlightMode - Nightlight mode setting
- * @property {string} temp - Temperature reading
- * @property {number} day - Day mode (0 or 1)
+ * @property {string} [nightlightMode] - Current nightlight color (actual hex color like '0xff5733' or 'off') - only in requested status, most accurate source
+ * @property {string} [temp] - Temperature reading (format varies: 'value1:value2:value3' or 'value1:notSupported') - only in requested status
+ * @property {-1 | 0 | 1} day - Day mode (0=night, 1=day, -1=unknown)
  */
 
 /**
@@ -85,14 +100,136 @@
 
  */
 
+/**
+ * Legacy status message from device (MQTT /status)
+ *
+ * This is the older undocumented status topic that contains critical lifecycle information
+ * not available in the documented /data/status topic, including:
+ * - shutDown field: Indicates device power state changes ('userShutdown', 'nA', etc.)
+ * - Startup detection: Low upTime values, utcTime: 0 after power on
+ * - Full hardware diagnostics: battery voltage, memory stats, temperatures
+ *
+ * Both documented and legacy status topics are necessary for complete device monitoring.
+ *
+ * @typedef {Object} YotoStatusLegacyMessage
+ * @property {YotoLegacyStatus} status - Legacy status object with full hardware details
+ */
+
+/**
+ * Legacy MQTT status payload structure (undocumented)
+ *
+ * Contains all fields from documented status plus additional lifecycle and diagnostic fields.
+ *
+ * @typedef {Object} YotoLegacyStatus
+ * @property {number} statusVersion - Status message version
+ * @property {string} fwVersion - Firmware version
+ * @property {string} shutDown - Power state: 'nA' = device running, any other value = shutting down/shut down (e.g., 'userShutdown') - ONLY in legacy topic
+ * @property {number} totalDisk - Total disk space in bytes
+ * @property {string} productType - Product type identifier
+ * @property {number} wifiStrength - WiFi signal strength in dBm
+ * @property {string} ssid - WiFi SSID
+ * @property {number} rtcResetReasonPRO - RTC reset reason (PRO)
+ * @property {number} rtcResetReasonAPP - RTC reset reason (APP)
+ * @property {number} rtcWakeupCause - RTC wakeup cause code
+ * @property {number} espResetReason - ESP reset reason code
+ * @property {string} sd_info - SD card information string
+ * @property {number} battery - Raw battery voltage in millivolts
+ * @property {string} powerCaps - Power capabilities
+ * @property {number} batteryLevel - Battery level percentage
+ * @property {number} batteryTemp - Battery temperature
+ * @property {string} batteryData - Battery data string (format: 'val1:val2:val3')
+ * @property {number} batteryLevelRaw - Raw battery level reading
+ * @property {number} free - Free memory in bytes
+ * @property {number} freeDMA - Free DMA memory in bytes
+ * @property {number} free32 - Free 32-bit memory in bytes
+ * @property {number} upTime - Device uptime in seconds (low values indicate recent startup)
+ * @property {number} utcTime - UTC timestamp (0 indicates fresh startup before time sync)
+ * @property {number} aliveTime - Total alive time in seconds
+ * @property {number} accelTemp - Accelerometer temperature in Celsius
+ * @property {string} batteryProfile - Battery profile identifier
+ * @property {number} freeDisk - Free disk space in bytes
+ * @property {number} failReason - Failure reason code
+ * @property {number} failData - Failure data
+ * @property {number} shutdownTimeout - Shutdown timeout in seconds
+ * @property {number} utcOffset - UTC offset in seconds
+ * @property {string} nfcErrs - NFC error rates (format: 'xx.xx%-xx.xx%')
+ * @property {number} dbatTimeout - DBAT timeout in seconds
+ * @property {number} charging - Charging state (0 or 1)
+ * @property {0 | 1 | 2 | 3} powerSrc - Power source (0=battery, 1=V2 dock, 2=USB-C, 3=Qi)
+ * @property {string} activeCard - Active card ID or 'none'
+ * @property {0 | 1 | 2} cardInserted - Card insertion state (0=none, 1=physical, 2=remote)
+ * @property {number} playingStatus - Playing status code
+ * @property {number} headphones - Headphones connected (0 or 1)
+ * @property {number} wifiRestarts - WiFi restart count
+ * @property {number} qiOtp - Qi OTP value
+ * @property {number} buzzErrors - Buzzer error count
+ * @property {number} dnowBrightness - Current display brightness
+ * @property {number} dayBright - Day brightness setting
+ * @property {number} nightBright - Night brightness setting
+ * @property {number} errorsLogged - Number of errors logged
+ * @property {number} twdt - Task watchdog timer value
+ * @property {number} bluetoothHp - Bluetooth headphones state (0 or 1)
+ * @property {string} nightlightMode - Current nightlight color (hex color like '0xff5733' or 'off')
+ * @property {number} bgDownload - Background download state
+ * @property {number} bytesPS - Bytes per second
+ * @property {-1 | 0 | 1} day - Day mode (0=night, 1=day, -1=unknown)
+ * @property {string} temp - Temperature readings (format: 'val1:val2:val3')
+ * @property {number} als - Ambient light sensor reading
+ * @property {number} volume - System/max volume level (0-100 percentage, represents 0-16 hardware scale, maps to volumeMax in events)
+ * @property {number} userVolume - User volume setting (0-100 percentage, represents 0-16 hardware scale, maps to volume in events)
+ * @property {'12' | '24'} timeFormat - Time format preference
+ * @property {number} chgStatLevel - Charge state level
+ * @property {number} missedLogs - Missed log count
+ * @property {number} nfcLock - NFC lock state
+ * @property {number} batteryFullPct - Battery full percentage threshold
+ */
+
 /**
  * MQTT connection state
  * @typedef {'disconnected' | 'connected' | 'reconnecting'} YotoMqttConnectionState
  */
 
+/**
+ * Events message callback
+ * @callback EventsCallback
+ * @param {string} topic - Raw MQTT topic string
+ * @param {YotoEventsMessage} payload - Events message payload
+ */
+
+/**
+ * Status message callback
+ * @callback StatusCallback
+ * @param {string} topic - Raw MQTT topic string
+ * @param {YotoStatusMessage} payload - Status message payload
+ */
+
+/**
+ * Legacy status message callback
+ * @callback StatusLegacyCallback
+ * @param {string} topic - Raw MQTT topic string
+ * @param {YotoStatusLegacyMessage} payload - Legacy status message payload with lifecycle events
+ */
+
+/**
+ * Response message callback
+ * @callback ResponseCallback
+ * @param {string} topic - Raw MQTT topic string
+ * @param {YotoResponseMessage} payload - Response message payload
+ */
+
+/**
+ * Unknown message callback
+ * @callback UnknownCallback
+ * @param {string} topic - Raw MQTT topic string
+ * @param {any} payload - Unknown message payload
+ */
+
 import { EventEmitter } from 'events'
 import {
   getSubscriptionTopics,
+  getEventsTopic,
+  getStatusTopic,
+  getResponseTopic,
   parseTopic,
   getEventsRequestTopic,
   getStatusRequestTopic,
@@ -118,9 +255,14 @@ import { commands } from './commands.js'
  * Yoto MQTT Client class
  * @extends EventEmitter
  *
- * @fires YotoMqttClient#events
- * @fires YotoMqttClient#status
- * @fires YotoMqttClient#response
+ * Device automatically publishes status updates every 5 minutes when connected.
+ * Status can also be requested on-demand via requestStatus() and requestEvents().
+ *
+ * @fires YotoMqttClient#events - Emits (topic, payload) when device sends events
+ * @fires YotoMqttClient#status - Emits (topic, payload) when device sends status (automatic every 5 min, or on-demand)
+ * @fires YotoMqttClient#status-legacy - Emits (topic, payload) when device sends legacy status with lifecycle events
+ * @fires YotoMqttClient#response - Emits (topic, payload) when device responds to commands
+ * @fires YotoMqttClient#unknown - Emits (topic, payload) when receiving unknown message type
  * @fires YotoMqttClient#connected
  * @fires YotoMqttClient#disconnected
  * @fires YotoMqttClient#reconnecting
@@ -209,14 +351,43 @@ export class YotoMqttClient extends EventEmitter {
 
   /**
    * Subscribe to device topics
+   * @param {Array<'events' | 'status' | 'response'> | 'all'} [types='all'] - Topic types to subscribe to, or 'all' for all topics
    * @returns {Promise<void>}
+   * @example
+   * // Subscribe to all topics (default)
+   * await client.subscribe()
+   * await client.subscribe('all')
+   *
+   * // Subscribe to specific topics
+   * await client.subscribe(['events', 'status'])
+   * await client.subscribe(['response'])
    */
-  async #subscribe () {
-    const topics = getSubscriptionTopics(this.deviceId)
+  async subscribe (types = 'all') {
+    let topicsToSubscribe = []
+
+    if (types === 'all') {
+      // Subscribe to all device topics
+      topicsToSubscribe = getSubscriptionTopics(this.deviceId)
+    } else {
+      // Subscribe to specific topic types
+      const typeArray = Array.isArray(types) ? types : [types]
+
+      for (const type of typeArray) {
+        if (type === 'events') {
+          topicsToSubscribe.push(...getEventsTopic(this.deviceId))
+        } else if (type === 'status') {
+          topicsToSubscribe.push(...getStatusTopic(this.deviceId))
+        } else if (type === 'response') {
+          topicsToSubscribe.push(getResponseTopic(this.deviceId))
+        } else {
+          throw new Error(`Invalid topic type: ${type}. Must be 'events', 'status', 'response', or 'all'`)
+        }
+      }
+    }
 
     // Wait for all subscriptions to complete
     await Promise.all(
-      topics.map((topic) => {
+      topicsToSubscribe.map((topic) => {
         return new Promise((resolve, reject) => {
           this.mqttClient.subscribe(topic, (err) => {
             if (err) {
@@ -232,6 +403,14 @@ export class YotoMqttClient extends EventEmitter {
     )
   }
 
+  /**
+   * Subscribe to device topics (internal - used by autoSubscribe)
+   * @returns {Promise<void>}
+   */
+  async #subscribe () {
+    return this.subscribe('all')
+  }
+
   /**
    * Handle incoming MQTT message
    * @param {string} topic - MQTT topic
@@ -245,21 +424,22 @@ export class YotoMqttClient extends EventEmitter {
       return
     }
 
-    // Ignore unknown message types
-    if (messageType === 'unknown') {
-      return
-    }
-
     try {
       const payload = JSON.parse(message.toString())
 
-      // Emit typed events based on message type
+      // Emit typed events based on message type, including raw topic
       if (messageType === 'events') {
-        this.emit('events', /** @type {YotoEventsMessage} */ (payload))
+        this.emit('events', topic, /** @type {YotoEventsMessage} */ (payload))
       } else if (messageType === 'status') {
-        this.emit('status', /** @type {YotoStatusMessage} */ (payload))
+        this.emit('status', topic, /** @type {YotoStatusMessage} */ (payload))
+      } else if (messageType === 'status-legacy') {
+        // Legacy status topic contains lifecycle events (shutdown, startup) and full hardware diagnostics
+        // The documented /data/status topic does not include these critical lifecycle fields
+        this.emit('status-legacy', topic, /** @type {YotoStatusLegacyMessage} */ (payload))
       } else if (messageType === 'response') {
-        this.emit('response', /** @type {YotoResponseMessage} */ (payload))
+        this.emit('response', topic, /** @type {YotoResponseMessage} */ (payload))
+      } else if (messageType === 'unknown') {
+        this.emit('unknown', topic, payload)
       }
     } catch (err) {
       const error = /** @type {Error} */ (err)
@@ -346,20 +526,22 @@ export class YotoMqttClient extends EventEmitter {
 
   /**
    * Request current events from device
+   * @param {string} [body=''] - Optional request body for tracking/identification
    * @returns {Promise<void>}
    */
-  async requestEvents () {
+  async requestEvents (body = '') {
     const topic = getEventsRequestTopic(this.deviceId)
-    return this.#publish(topic, '')
+    return this.#publish(topic, body)
   }
 
   /**
    * Request current status from device
+   * @param {string} [body=''] - Optional request body for tracking/identification
    * @returns {Promise<void>}
    */
-  async requestStatus () {
+  async requestStatus (body = '') {
     const topic = getStatusRequestTopic(this.deviceId)
-    return this.#publish(topic, '')
+    return this.#publish(topic, body)
   }
 
   /**

package/lib/mqtt/commands.d.ts

@@ -1,7 +1,100 @@
+/**
+ * MQTT Command Builders for Yoto Players
+ *
+ * Type-safe builders for constructing MQTT command payloads
+ * @see https://yoto.dev/players-mqtt/
+ */
+/**
+ * Volume command payload
+ * @see https://yoto.dev/players-mqtt/mqtt-docs/#deviceidcommandvolumeset
+ * @typedef {Object} YotoVolumeCommand
+ * @property {number} volume - Volume level [0-100]
+ */
+/**
+ * Ambient light command payload
+ * @see https://yoto.dev/players-mqtt/mqtt-docs/#deviceidcommandambientsset
+ * @typedef {Object} YotoAmbientCommand
+ * @property {number} r - Red intensity [0-255]
+ * @property {number} g - Green intensity [0-255]
+ * @property {number} b - Blue intensity [0-255]
+ */
+/**
+ * Sleep timer command payload
+ * @see https://yoto.dev/players-mqtt/mqtt-docs/#deviceidcommandsleep-timerset
+ * @typedef {Object} YotoSleepTimerCommand
+ * @property {number} seconds - Timer duration in seconds (0 to disable)
+ */
+/**
+ * Card start command payload
+ * @see https://yoto.dev/players-mqtt/mqtt-docs/#deviceidcommandcardstart
+ * @typedef {Object} YotoCardStartCommand
+ * @property {string} uri - Card URI (e.g., "https://yoto.io/<cardID>")
+ * @property {string} [chapterKey] - Chapter to start from
+ * @property {string} [trackKey] - Track to start from
+ * @property {number} [secondsIn] - Playback start offset in seconds
+ * @property {number} [cutOff] - Playback stop offset in seconds
+ * @property {boolean} [anyButtonStop] - Whether button press stops playback
+ */
+/**
+ * Bluetooth command payload
+ * @see https://yoto.dev/players-mqtt/mqtt-docs/#deviceidcommandbluetooth
+ * @typedef {Object} YotoBluetoothCommand
+ * @property {string} [action] - Bluetooth action (e.g., "on")
+ * @property {boolean | string} [mode] - Bluetooth mode (true for audio source, "bt_speaker" for sink)
+ * @property {number} [rssi] - RSSI threshold for auto-connect
+ * @property {string} [name] - Target Bluetooth device name
+ * @property {string} [mac] - Target Bluetooth MAC address
+ */
+/**
+ * Display preview command payload
+ * @see https://yoto.dev/players-mqtt/mqtt-docs/#deviceidcommanddisplaypreview
+ * @typedef {Object} YotoDisplayPreviewCommand
+ * @property {string} uri - Filepath to icon asset
+ * @property {number} timeout - Display duration in seconds
+ * @property {0 | 1} animated - Whether icon is animated (1) or static (0)
+ */
+/**
+ * Create a volume set command
+ * @param {number} volume - Volume level [0-100]
+ * @returns {YotoVolumeCommand}
+ * @throws {Error} If volume is out of range
+ */
 export function createVolumeCommand(volume: number): YotoVolumeCommand;
+/**
+ * Create an ambient light set command
+ * @param {number} r - Red intensity [0-255]
+ * @param {number} g - Green intensity [0-255]
+ * @param {number} b - Blue intensity [0-255]
+ * @returns {YotoAmbientCommand}
+ * @throws {Error} If any color value is out of range
+ */
 export function createAmbientCommand(r: number, g: number, b: number): YotoAmbientCommand;
+/**
+ * Create an ambient light command from hex color
+ * @param {string} hexColor - Hex color string (e.g., "#FF0000" or "FF0000")
+ * @returns {YotoAmbientCommand}
+ * @throws {Error} If hex color is invalid
+ */
 export function createAmbientCommandFromHex(hexColor: string): YotoAmbientCommand;
+/**
+ * Create a sleep timer set command
+ * @param {number} seconds - Timer duration in seconds (0 to disable)
+ * @returns {YotoSleepTimerCommand}
+ * @throws {Error} If seconds is negative
+ */
 export function createSleepTimerCommand(seconds: number): YotoSleepTimerCommand;
+/**
+ * Create a card start command
+ * @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
+ * @returns {YotoCardStartCommand}
+ * @throws {Error} If uri is missing
+ */
 export function createCardStartCommand(options: {
     uri: string;
     chapterKey?: string | undefined;
@@ -10,6 +103,16 @@ export function createCardStartCommand(options: {
     cutOff?: number | undefined;
     anyButtonStop?: boolean | undefined;
 }): YotoCardStartCommand;
+/**
+ * Create a bluetooth on command
+ * @param {Object} [options] - Bluetooth options
+ * @param {string} [options.action] - Bluetooth action (e.g., "on")
+ * @param {boolean | string} [options.mode] - Bluetooth mode (true for audio source, "bt_speaker" for sink)
+ * @param {number} [options.rssi] - RSSI threshold for auto-connect
+ * @param {string} [options.name] - Target Bluetooth device name
+ * @param {string} [options.mac] - Target Bluetooth MAC address
+ * @returns {YotoBluetoothCommand}
+ */
 export function createBluetoothOnCommand(options?: {
     action?: string | undefined;
     mode?: string | boolean | undefined;
@@ -17,8 +120,25 @@ export function createBluetoothOnCommand(options?: {
     name?: string | undefined;
     mac?: string | undefined;
 }): YotoBluetoothCommand;
+/**
+ * Create a bluetooth speaker mode command
+ * @returns {YotoBluetoothCommand}
+ */
 export function createBluetoothSpeakerCommand(): YotoBluetoothCommand;
+/**
+ * Create a bluetooth audio source mode command
+ * @returns {YotoBluetoothCommand}
+ */
 export function createBluetoothAudioSourceCommand(): YotoBluetoothCommand;
+/**
+ * Create a display preview command
+ * @param {Object} options - Display preview options
+ * @param {string} options.uri - Filepath to icon asset
+ * @param {number} options.timeout - Display duration in seconds
+ * @param {boolean} options.animated - Whether icon is animated
+ * @returns {YotoDisplayPreviewCommand}
+ * @throws {Error} If uri or timeout is missing
+ */
 export function createDisplayPreviewCommand(options: {
     uri: string;
     timeout: number;
@@ -35,35 +155,110 @@ export namespace commands {
     export { createBluetoothAudioSourceCommand as bluetoothAudioSource };
     export { createDisplayPreviewCommand as displayPreview };
 }
+/**
+ * Volume command payload
+ */
 export type YotoVolumeCommand = {
+    /**
+     * - Volume level [0-100]
+     */
     volume: number;
 };
+/**
+ * Ambient light command payload
+ */
 export type YotoAmbientCommand = {
+    /**
+     * - Red intensity [0-255]
+     */
     r: number;
+    /**
+     * - Green intensity [0-255]
+     */
     g: number;
+    /**
+     * - Blue intensity [0-255]
+     */
     b: number;
 };
+/**
+ * Sleep timer command payload
+ */
 export type YotoSleepTimerCommand = {
+    /**
+     * - Timer duration in seconds (0 to disable)
+     */
     seconds: number;
 };
+/**
+ * Card start command payload
+ */
 export type YotoCardStartCommand = {
+    /**
+     * - Card URI (e.g., "https://yoto.io/<cardID>")
+     */
     uri: 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;
 };
+/**
+ * Bluetooth command payload
+ */
 export type YotoBluetoothCommand = {
+    /**
+     * - Bluetooth action (e.g., "on")
+     */
     action?: string;
+    /**
+     * - Bluetooth mode (true for audio source, "bt_speaker" for sink)
+     */
     mode?: boolean | string;
+    /**
+     * - RSSI threshold for auto-connect
+     */
     rssi?: number;
+    /**
+     * - Target Bluetooth device name
+     */
     name?: string;
+    /**
+     * - Target Bluetooth MAC address
+     */
     mac?: string;
 };
+/**
+ * Display preview command payload
+ */
 export type YotoDisplayPreviewCommand = {
+    /**
+     * - Filepath to icon asset
+     */
     uri: string;
+    /**
+     * - Display duration in seconds
+     */
     timeout: number;
+    /**
+     * - Whether icon is animated (1) or static (0)
+     */
     animated: 0 | 1;
 };
 //# sourceMappingURL=commands.d.ts.map

package/lib/mqtt/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["commands.js"],"names":[],"mappings":"AAwEA,4CAJW,MAAM,GACJ,iBAAiB,CAS7B;AAUD,wCANW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,kBAAkB,CAS9B;AAQD,sDAJW,MAAM,GACJ,kBAAkB,CAgB9B;AAQD,iDAJW,MAAM,GACJ,qBAAqB,CASjC;AAcD,gDATG;IAAwB,GAAG,EAAnB,MAAM;IACW,UAAU;IACV,QAAQ;IACR,SAAS;IACT,MAAM;IACL,aAAa;CACvC,GAAU,oBAAoB,CAkBhC;AAYD,mDAPG;IAAyB,MAAM;IACI,IAAI;IACd,IAAI;IACJ,IAAI;IACJ,GAAG;CAC5B,GAAU,oBAAoB,CAahC;AAMD,iDAFa,oBAAoB,CAIhC;AAMD,qDAFa,oBAAoB,CAIhC;AAWD,qDANG;IAAwB,GAAG,EAAnB,MAAM;IACU,OAAO,EAAvB,MAAM;IACW,QAAQ,EAAzB,OAAO;CACf,GAAU,yBAAyB,CAiBrC;;;;;;;;;;;;;YA/Ma,MAAM;;;OAON,MAAM;OACN,MAAM;OACN,MAAM;;;aAON,MAAM;;;SAON,MAAM;iBACN,MAAM;eACN,MAAM;gBACN,MAAM;aACN,MAAM;oBACN,OAAO;;;aAOP,MAAM;WACN,OAAO,GAAG,MAAM;WAChB,MAAM;WACN,MAAM;UACN,MAAM;;;SAON,MAAM;aACN,MAAM;cACN,CAAC,GAAG,CAAC"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["commands.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;GAKG;AAEH;;;;;;;GAOG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,4CAJW,MAAM,GACJ,iBAAiB,CAS7B;AAED;;;;;;;GAOG;AACH,wCANW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,kBAAkB,CAS9B;AAED;;;;;GAKG;AACH,sDAJW,MAAM,GACJ,kBAAkB,CAgB9B;AAED;;;;;GAKG;AACH,iDAJW,MAAM,GACJ,qBAAqB,CASjC;AAED;;;;;;;;;;;GAWG;AACH,gDATG;IAAwB,GAAG,EAAnB,MAAM;IACW,UAAU;IACV,QAAQ;IACR,SAAS;IACT,MAAM;IACL,aAAa;CACvC,GAAU,oBAAoB,CAkBhC;AAED;;;;;;;;;GASG;AACH,mDAPG;IAAyB,MAAM;IACI,IAAI;IACd,IAAI;IACJ,IAAI;IACJ,GAAG;CAC5B,GAAU,oBAAoB,CAahC;AAED;;;GAGG;AACH,iDAFa,oBAAoB,CAIhC;AAED;;;GAGG;AACH,qDAFa,oBAAoB,CAIhC;AAED;;;;;;;;GAQG;AACH,qDANG;IAAwB,GAAG,EAAnB,MAAM;IACU,OAAO,EAAvB,MAAM;IACW,QAAQ,EAAzB,OAAO;CACf,GAAU,yBAAyB,CAiBrC;;;;;;;;;;;;;;;;;;;YA/Ma,MAAM;;;;;;;;;OAON,MAAM;;;;OACN,MAAM;;;;OACN,MAAM;;;;;;;;;aAON,MAAM;;;;;;;;;SAON,MAAM;;;;iBACN,MAAM;;;;eACN,MAAM;;;;gBACN,MAAM;;;;aACN,MAAM;;;;oBACN,OAAO;;;;;;;;;aAOP,MAAM;;;;WACN,OAAO,GAAG,MAAM;;;;WAChB,MAAM;;;;WACN,MAAM;;;;UACN,MAAM;;;;;;;;;SAON,MAAM;;;;aACN,MAAM;;;;cACN,CAAC,GAAG,CAAC"}