yoto-nodejs-client 0.0.5 → 0.0.7

package/lib/mqtt/client.d.ts

@@ -1,21 +1,27 @@
 /**
  * Yoto MQTT Client class
- * @extends EventEmitter
+ * @extends {EventEmitter<YotoMqttClientEventMap>}
  *
  * 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
- * @fires YotoMqttClient#error
+ * Events:
+ * - 'connect' - Emitted on successful (re)connection (connack rc=0). Passes connack packet; when sessionPresent is true and clean is false, you can rely on stored session and avoid re-subscribing. Auto-subscribe (if enabled) runs after connect and may emit errors.
+ * - 'disconnect' - Emitted after receiving disconnect packet from broker. MQTT 5.0 feature. Passes metadata with disconnect packet.
+ * - 'close' - Emitted after a disconnection, passes metadata with close reason.
+ * - 'reconnect' - Emitted when a reconnect starts.
+ * - 'offline' - Emitted when the client goes offline.
+ * - 'end' - Emitted when mqttClient.end() is called (after its callback returns).
+ * - 'error' - Emitted when the client cannot connect (connack rc != 0) or when a parsing error occurs.
+ * - 'packetsend' - Emitted when the client sends any packet (including publish and subscription packets).
+ * - 'packetreceive' - Emitted when the client receives any packet.
+ * - 'events' - Device sends events, passes (topic, payload).
+ * - 'status' - Device sends status, passes (topic, payload).
+ * - 'status-legacy' - Device sends legacy status with lifecycle events, passes (topic, payload).
+ * - 'response' - Device responds to commands, passes (topic, payload).
+ * - 'unknown' - Unknown message type received, passes (topic, payload).
  */
-export class YotoMqttClient extends EventEmitter<any> {
+export class YotoMqttClient extends EventEmitter<YotoMqttClientEventMap> {
     /**
      * Create a Yoto MQTT client
      * @param {MqttClient} mqttClient - Underlying MQTT client
@@ -26,20 +32,9 @@ export class YotoMqttClient extends EventEmitter<any> {
     constructor(mqttClient: MqttClient, deviceId: string, options?: {
         autoSubscribe?: boolean | undefined;
     });
-    mqttClient: MqttClient;
-    deviceId: string;
-    autoSubscribe: boolean;
-    commands: {
-        volume: typeof import("./commands.js").createVolumeCommand;
-        ambient: typeof import("./commands.js").createAmbientCommand;
-        ambientFromHex: typeof import("./commands.js").createAmbientCommandFromHex;
-        sleepTimer: typeof import("./commands.js").createSleepTimerCommand;
-        cardStart: typeof import("./commands.js").createCardStartCommand;
-        bluetoothOn: typeof import("./commands.js").createBluetoothOnCommand;
-        bluetoothSpeaker: typeof import("./commands.js").createBluetoothSpeakerCommand;
-        bluetoothAudioSource: typeof import("./commands.js").createBluetoothAudioSourceCommand;
-        displayPreview: typeof import("./commands.js").createDisplayPreviewCommand;
-    };
+    /** @type {typeof commands} */ commands: typeof commands;
+    /** @type {MqttClient} */ mqttClient: MqttClient;
+    /** @type {string} */ deviceId: string;
     /**
      * Get current connection state
      * @returns {YotoMqttConnectionState}
@@ -218,6 +213,44 @@ export class YotoMqttClient extends EventEmitter<any> {
     }): Promise<void>;
     #private;
 }
+export type PlaybackStatus = "playing" | "paused" | "stopped" | "loading";
+/**
+ * MQTT disconnect event metadata (from MQTT disconnect packet)
+ */
+export type YotoMqttClientDisconnectMetadata = {
+    /**
+     * - MQTT disconnect packet
+     */
+    packet: IDisconnectPacket;
+};
+/**
+ * MQTT close event metadata (from connection close)
+ */
+export type YotoMqttClientCloseMetadata = {
+    /**
+     * - Close reason
+     */
+    reason: "close";
+};
+/**
+ * Event map for YotoMqttClient
+ */
+export type YotoMqttClientEventMap = {
+    "connect": [IConnackPacket];
+    "disconnect": [YotoMqttClientDisconnectMetadata];
+    "close": [YotoMqttClientCloseMetadata];
+    "reconnect": [];
+    "offline": [];
+    "end": [];
+    "error": [Error];
+    "events": [string, YotoEventsMessage];
+    "status": [string, YotoStatusMessage];
+    "status-legacy": [string, YotoStatusLegacyMessage];
+    "response": [string, YotoResponseMessage];
+    "unknown": [string, any];
+    "packetsend": [Packet];
+    "packetreceive": [Packet];
+};
 /**
  * Events message from device
  * Note: Messages are partial - only changed fields are included
@@ -266,7 +299,7 @@ export type YotoEventsMessage = {
     /**
      * - Source of playback (e.g., "card", "remote", "MQTT")
      */
-    source?: string;
+    source?: "card" | "remote" | "MQTT";
     /**
      * - ISO8601 format timestamp
      */
@@ -290,7 +323,7 @@ export type YotoEventsMessage = {
     /**
      * - Playback status
      */
-    playbackStatus?: "playing" | "paused" | "stopped" | "loading" | string;
+    playbackStatus?: PlaybackStatus;
     /**
      * - Seconds remaining on sleep timer
      */
@@ -334,7 +367,7 @@ export type YotoMqttStatus = {
      */
     batteryLevel: number;
     /**
-     * - Ambient light sensor reading
+     * - Ambient light sensor reading TODO: Find range/units
      */
     als: number;
     /**
@@ -374,11 +407,11 @@ export type YotoMqttStatus = {
      */
     dnowBrightness: number;
     /**
-     * - Day brightness setting (Integer 0-100)
+     * - Day brightness setting (Integer 0-100, 255 when 'auto')
      */
     dayBright: number;
     /**
-     * - Night brightness setting (Integer 0-100)
+     * - Night brightness setting (Integer 0-100, 255 when 'auto')
      */
     nightBright: number;
     /**
@@ -402,7 +435,7 @@ export type YotoMqttStatus = {
      */
     nightlightMode?: string;
     /**
-     * - Temperature reading (format varies: 'value1:value2:value3' or 'value1:notSupported') - only in requested status
+     * - Temperature reading (format varies: 'value1:value2:value3' or 'value1:notSupported') - only in requested status. value2, when a number, is the temp in Celcius
      */
     temp?: string;
     /**
@@ -410,6 +443,55 @@ export type YotoMqttStatus = {
      */
     day: -1 | 0 | 1;
 };
+/**
+ * Response message from device
+ */
+export type YotoResponseStatusKnown = {
+    /**
+     * - Volume command result
+     */
+    volume?: "OK" | "FAIL";
+    /**
+     * - Ambients command result
+     */
+    ambients?: "OK" | "FAIL";
+    /**
+     * - Card command result
+     */
+    card?: "OK" | "FAIL";
+    /**
+     * - Events request result (alternate key to 'events/request')
+     */
+    events?: "OK" | "FAIL";
+    /**
+     * - Status request result (alternate key to 'status/request')
+     */
+    status?: "OK" | "FAIL";
+    /**
+     * - Bluetooth command result
+     */
+    bluetooth?: "OK" | "FAIL";
+    /**
+     * - Display command result
+     */
+    display?: "OK" | "FAIL";
+    /**
+     * - Reboot command result
+     */
+    reboot?: "OK" | "FAIL";
+    /**
+     * - Stringified JSON from original request
+     */
+    req_body: string;
+    /**
+     * - Sleep timer command result (alternate key to 'sleep-timer')
+     */
+    sleepTimer?: "OK" | "FAIL";
+};
+/**
+ * Response message from device
+ */
+export type YotoResponseStatus = YotoResponseStatusKnown & Record<string, "OK" | "FAIL" | string | undefined> & Partial<Record<"status/request" | "events/request" | "sleep-timer", "OK" | "FAIL">>;
 /**
  * Response message from device
  */
@@ -417,18 +499,7 @@ export type YotoResponseMessage = {
     /**
      * - Status object with dynamic resource keys
      */
-    status: {
-        volume?: "OK" | "FAIL" | undefined;
-        ambients?: "OK" | "FAIL" | undefined;
-        card?: "OK" | "FAIL" | undefined;
-        events?: "OK" | "FAIL" | undefined;
-        status?: "OK" | "FAIL" | undefined;
-        bluetooth?: "OK" | "FAIL" | undefined;
-        display?: "OK" | "FAIL" | undefined;
-        reboot?: "OK" | "FAIL" | undefined;
-        req_body: string;
-        sleepTimer: "OK" | "FAIL";
-    };
+    status: YotoResponseStatus;
 };
 /**
  * Legacy status message from device (MQTT /status)
@@ -622,15 +693,15 @@ export type YotoLegacyStatus = {
      */
     buzzErrors: number;
     /**
-     * - Current display brightness
+     * - Current display brightness (0-100, act)
      */
     dnowBrightness: number;
     /**
-     * - Day brightness setting
+     * - Day brightness setting (0-100, 255 when configed to 'auto')
      */
     dayBright: number;
     /**
-     * - Night brightness setting
+     * - Night brightness setting (0-100, 255 when configed to 'auto')
      */
     nightBright: number;
     /**
@@ -662,11 +733,11 @@ export type YotoLegacyStatus = {
      */
     day: -1 | 0 | 1;
     /**
-     * - Temperature readings (format: 'val1:val2:val3')
+     * - Temperature reading (format varies: 'value1:value2:value3' or 'value1:notSupported') - only in requested status. value2, when a number, is the temp in Celcius
      */
     temp: string;
     /**
-     * - Ambient light sensor reading
+     * - Ambient light sensor reading TODO: Find range/units
      */
     als: number;
     /**
@@ -723,5 +794,9 @@ export type ResponseCallback = (topic: string, payload: YotoResponseMessage) =>
  */
 export type UnknownCallback = (topic: string, payload: any) => any;
 import { EventEmitter } from 'events';
+import { commands } from './commands.js';
 import type { MqttClient } from 'mqtt';
+import type { IDisconnectPacket } from 'mqtt';
+import type { IConnackPacket } from 'mqtt';
+import type { Packet } from 'mqtt';
 //# sourceMappingURL=client.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["client.js"],"names":[],"mappings":"AA6PA;;;;;;;;;;;;;;;;GAgBG;AACH;IACE;;;;;;OAMG;IACH,wBALW,UAAU,YACV,MAAM,YAEd;QAA0B,aAAa;KACzC,EAaA;IATC,uBAA4B;IAC5B,iBAAwB;IACxB,uBAAoD;IAMpD;;;;;;;;;;MAAwB;IAG1B;;;OAGG;IACH,aAFa,uBAAuB,CAMnC;IAED;;;OAGG;IACH,iBAFa,OAAO,CAInB;IA2CD;;;;;;;;;;;;OAYG;IACH,kBAXW,KAAK,CAAC,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC,GAAG,KAAK,GAC7C,OAAO,CAAC,IAAI,CAAC,CAiDzB;IA8CD;;;OAGG;IACH,WAFa,OAAO,CAAC,IAAI,CAAC,CA8BzB;IAED;;;OAGG;IACH,cAFa,OAAO,CAAC,IAAI,CAAC,CAiBzB;IAwBD;;;;OAIG;IACH,qBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAMzB;IAED;;;;;;OAMG;IACH,cALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAMzB;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAMzB;IAED;;;;OAIG;IACH,uBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAMzB;IAED;;;OAGG;IACH,UAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;;;;;;;;OAUG;IACH,mBARG;QAAwB,GAAG,EAAnB,MAAM;QACW,UAAU;QACV,QAAQ;QACR,SAAS;QACT,MAAM;QACL,aAAa;KACvC,GAAU,OAAO,CAAC,IAAI,CAAC,CAMzB;IAED;;;OAGG;IACH,YAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;OAGG;IACH,aAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;OAGG;IACH,cAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;;;;;;;OASG;IACH,sBAPG;QAAyB,MAAM;QACI,IAAI;QACd,IAAI;QACJ,IAAI;QACJ,GAAG;KAC5B,GAAU,OAAO,CAAC,IAAI,CAAC,CAMzB;IAED;;;OAGG;IACH,gBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;OAGG;IACH,wBAFa,OAAO,CAAC,IAAI,CAAC,CAMzB;IAED;;;OAGG;IACH,4BAFa,OAAO,CAAC,IAAI,CAAC,CAMzB;IAED;;;OAGG;IACH,wBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;OAGG;IACH,oBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;OAGG;IACH,uBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;OAGG;IACH,qBAFa,OAAO,CAAC,IAAI,CAAC,CAKzB;IAED;;;;;;;OAOG;IACH,wBALG;QAAwB,GAAG,EAAnB,MAAM;QACU,OAAO,EAAvB,MAAM;QACW,QAAQ,EAAzB,OAAO;KACf,GAAU,OAAO,CAAC,IAAI,CAAC,CAMzB;;CACF;;;;;;;;;gBA/sBa,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,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM;;;;wBACrD,MAAM;;;;;;;;;;;;;;YAYN,cAAc;;;;;;;;;;;;mBAUd,MAAM;;;;eACN,MAAM;;;;iBACN,MAAM;;;;kBACN,MAAM;;;;SACN,MAAM;;;;cACN,MAAM;;;;qBACN,MAAM;;;;iBACN,MAAM;;;;cACN,MAAM;;;;gBACN,MAAM;;;;kBACN,CAAC,GAAG,CAAC,GAAG,CAAC;;;;mBACT,MAAM;;;;gBACN,OAAO;;;;oBACP,MAAM;;;;eACN,MAAM;;;;iBACN,MAAM;;;;iBACN,OAAO;;;;YACP,MAAM;;;;gBACN,MAAM;;;;gBACN,IAAI,GAAG,IAAI;;;;qBACX,MAAM;;;;WACN,MAAM;;;;SACN,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;;;;;;;;;YAQrB;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;;;;;;;;;;;;;;;;;YAca,gBAAgB;;;;;;;;;;;mBAShB,MAAM;;;;eACN,MAAM;;;;cACN,MAAM;;;;eACN,MAAM;;;;iBACN,MAAM;;;;kBACN,MAAM;;;;UACN,MAAM;;;;uBACN,MAAM;;;;uBACN,MAAM;;;;oBACN,MAAM;;;;oBACN,MAAM;;;;aACN,MAAM;;;;aACN,MAAM;;;;eACN,MAAM;;;;kBACN,MAAM;;;;iBACN,MAAM;;;;iBACN,MAAM;;;;qBACN,MAAM;;;;UACN,MAAM;;;;aACN,MAAM;;;;YACN,MAAM;;;;YACN,MAAM;;;;aACN,MAAM;;;;eACN,MAAM;;;;eACN,MAAM;;;;oBACN,MAAM;;;;cACN,MAAM;;;;gBACN,MAAM;;;;cACN,MAAM;;;;qBACN,MAAM;;;;eACN,MAAM;;;;aACN,MAAM;;;;iBACN,MAAM;;;;cACN,MAAM;;;;cACN,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;;;;gBACb,MAAM;;;;kBACN,CAAC,GAAG,CAAC,GAAG,CAAC;;;;mBACT,MAAM;;;;gBACN,MAAM;;;;kBACN,MAAM;;;;WACN,MAAM;;;;gBACN,MAAM;;;;oBACN,MAAM;;;;eACN,MAAM;;;;iBACN,MAAM;;;;kBACN,MAAM;;;;UACN,MAAM;;;;iBACN,MAAM;;;;oBACN,MAAM;;;;gBACN,MAAM;;;;aACN,MAAM;;;;SACN,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;;;;UACV,MAAM;;;;SACN,MAAM;;;;YACN,MAAM;;;;gBACN,MAAM;;;;gBACN,IAAI,GAAG,IAAI;;;;kBACX,MAAM;;;;gBACN,MAAM;;;;aACN,MAAM;;;;oBACN,MAAM;;;;;sCAKP,cAAc,GAAG,WAAW,GAAG,cAAc;;;;qCAM/C,MAAM,WACN,iBAAiB;;;;qCAMjB,MAAM,WACN,iBAAiB;;;;2CAMjB,MAAM,WACN,uBAAuB;;;;uCAMvB,MAAM,WACN,mBAAmB;;;;sCAMnB,MAAM,WACN,GAAG;6BAGe,QAAQ;gCAtNN,MAAM"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["client.js"],"names":[],"mappings":"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"}

package/lib/mqtt/client.js

@@ -10,7 +10,43 @@
 // ============================================================================
 
 /**
- * @import { MqttClient } from 'mqtt'
+ * @import { MqttClient, IConnackPacket, IDisconnectPacket, Packet } from 'mqtt'
+ */
+
+/**
+  * @typedef {'playing' | 'paused' | 'stopped' | 'loading'} PlaybackStatus
+  */
+
+/**
+ * MQTT disconnect event metadata (from MQTT disconnect packet)
+ * @typedef {Object} YotoMqttClientDisconnectMetadata
+ * @property {IDisconnectPacket} packet - MQTT disconnect packet
+ */
+
+/**
+ * MQTT close event metadata (from connection close)
+ * @typedef {Object} YotoMqttClientCloseMetadata
+ * @property {'close'} reason - Close reason
+ */
+
+/**
+ * Event map for YotoMqttClient
+ * @typedef {{
+ *   'connect': [IConnackPacket],
+ *   'disconnect': [YotoMqttClientDisconnectMetadata],
+ *   'close': [YotoMqttClientCloseMetadata],
+ *   'reconnect': [],
+ *   'offline': [],
+ *   'end': [],
+ *   'error': [Error],
+ *   'events': [string, YotoEventsMessage],
+ *   'status': [string, YotoStatusMessage],
+ *   'status-legacy': [string, YotoStatusLegacyMessage],
+ *   'response': [string, YotoResponseMessage],
+ *   'unknown': [string, any],
+ *   'packetsend': [Packet],
+ *   'packetreceive': [Packet]
+ * }} YotoMqttClientEventMap
  */
 
 /**
@@ -28,13 +64,13 @@
  * @property {number} [trackLength] - Track duration in seconds
  * @property {number} [position] - Current position in seconds
  * @property {string} [cardId] - Currently playing card ID
- * @property {string} [source] - Source of playback (e.g., "card", "remote", "MQTT")
+ * @property {'card' | 'remote' | 'MQTT' } [source] - Source of playback (e.g., "card", "remote", "MQTT")
  * @property {string} [cardUpdatedAt] - ISO8601 format timestamp
  * @property {string} [chapterTitle] - Current chapter title
  * @property {string} [chapterKey] - Current chapter key
  * @property {string} [trackTitle] - Current track title
  * @property {string} [trackKey] - Current track key
- * @property {'playing' | 'paused' | 'stopped' | 'loading' | string} [playbackStatus] - Playback status
+ * @property {PlaybackStatus} [playbackStatus] - Playback status
  * @property {number} [sleepTimerSeconds] - Seconds remaining on sleep timer
  */
 
@@ -61,7 +97,7 @@
  * @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} als - Ambient light sensor reading TODO: Find range/units
  * @property {number} freeDisk - Free disk space in bytes
  * @property {number} shutdownTimeout - Shutdown timeout in seconds
  * @property {number} dbatTimeout - DBAT timeout
@@ -71,33 +107,46 @@
  * @property {number} playingStatus - Playing status code
  * @property {boolean} headphones - Headphones connected
  * @property {number} dnowBrightness - Current display brightness (Integer 0-100)
- * @property {number} dayBright - Day brightness setting (Integer 0-100)
- * @property {number} nightBright - Night brightness setting (Integer 0-100)
+ * @property {number} dayBright - Day brightness setting (Integer 0-100, 255 when 'auto')
+ * @property {number} nightBright - Night brightness setting (Integer 0-100, 255 when 'auto')
  * @property {boolean} bluetoothHp - Bluetooth headphones enabled
  * @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] - 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 {string} [temp] - Temperature reading (format varies: 'value1:value2:value3' or 'value1:notSupported') - only in requested status. value2, when a number, is the temp in Celcius
  * @property {-1 | 0 | 1} day - Day mode (0=night, 1=day, -1=unknown)
  */
 
 /**
  * Response message from device
  * @see https://yoto.dev/players-mqtt/mqtt-docs/#deviceidresponse
+ *
+ * Note: `status` contains dynamic keys and some keys may include slashes/dashes.
+ * Known (observed) non-identifier keys:
+ * - 'status/request' - Status request result
+ * - 'events/request' - Events request result
+ * - 'sleep-timer' - Sleep timer command result
+ *
+ * @typedef {Object} YotoResponseStatusKnown
+ * @property {'OK' | 'FAIL'} [volume] - Volume command result
+ * @property {'OK' | 'FAIL'} [ambients] - Ambients command result
+ * @property {'OK' | 'FAIL'} [card] - Card command result
+ * @property {'OK' | 'FAIL'} [events] - Events request result (alternate key to 'events/request')
+ * @property {'OK' | 'FAIL'} [status] - Status request result (alternate key to 'status/request')
+ * @property {'OK' | 'FAIL'} [bluetooth] - Bluetooth command result
+ * @property {'OK' | 'FAIL'} [display] - Display command result
+ * @property {'OK' | 'FAIL'} [reboot] - Reboot command result
+ * @property {string} req_body - Stringified JSON from original request
+ * @property {'OK' | 'FAIL'} [sleepTimer] - Sleep timer command result (alternate key to 'sleep-timer')
+ *
+ * @typedef {YotoResponseStatusKnown
+ *   & Record<string, 'OK' | 'FAIL' | string | undefined>
+ *   & Partial<Record<'status/request' | 'events/request' | 'sleep-timer', 'OK' | 'FAIL'>>
+ * } YotoResponseStatus
+ *
  * @typedef {Object} YotoResponseMessage
- * @property {Object} status - Status object with dynamic resource keys
- * @property {'OK' | 'FAIL'} [status.volume] - Volume command result
- * @property {'OK' | 'FAIL'} [status.ambients] - Ambients command result
- * @property {'OK' | 'FAIL'} [status.card] - Card command result
- * @property {'OK' | 'FAIL'} [status.events] - Events request result
- * @property {'OK' | 'FAIL'} [status.status] - Status request result
- * @property {'OK' | 'FAIL'} [status.bluetooth] - Bluetooth command result
- * @property {'OK' | 'FAIL'} [status.display] - Display command result
- * @property {'OK' | 'FAIL'} [status.reboot] - Reboot command result
- * @property {string} status.req_body - Stringified JSON from original request
- * @property {'OK' | 'FAIL'} status.sleepTimer - Sleep timer command result (note: actual field name is 'sleep-timer')
-
+ * @property {YotoResponseStatus} status - Status object with dynamic resource keys
  */
 
 /**
@@ -163,9 +212,9 @@
  * @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} dnowBrightness - Current display brightness (0-100, act)
+ * @property {number} dayBright - Day brightness setting (0-100, 255 when configed to 'auto')
+ * @property {number} nightBright - Night brightness setting (0-100, 255 when configed to 'auto')
  * @property {number} errorsLogged - Number of errors logged
  * @property {number} twdt - Task watchdog timer value
  * @property {number} bluetoothHp - Bluetooth headphones state (0 or 1)
@@ -173,8 +222,8 @@
  * @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 {string} temp - Temperature reading (format varies: 'value1:value2:value3' or 'value1:notSupported') - only in requested status. value2, when a number, is the temp in Celcius
+ * @property {number} als - Ambient light sensor reading TODO: Find range/units
  * @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
@@ -253,22 +302,33 @@ import { commands } from './commands.js'
 
 /**
  * Yoto MQTT Client class
- * @extends EventEmitter
+ * @extends {EventEmitter<YotoMqttClientEventMap>}
  *
  * 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
- * @fires YotoMqttClient#error
+ * Events:
+ * - 'connect' - Emitted on successful (re)connection (connack rc=0). Passes connack packet; when sessionPresent is true and clean is false, you can rely on stored session and avoid re-subscribing. Auto-subscribe (if enabled) runs after connect and may emit errors.
+ * - 'disconnect' - Emitted after receiving disconnect packet from broker. MQTT 5.0 feature. Passes metadata with disconnect packet.
+ * - 'close' - Emitted after a disconnection, passes metadata with close reason.
+ * - 'reconnect' - Emitted when a reconnect starts.
+ * - 'offline' - Emitted when the client goes offline.
+ * - 'end' - Emitted when mqttClient.end() is called (after its callback returns).
+ * - 'error' - Emitted when the client cannot connect (connack rc != 0) or when a parsing error occurs.
+ * - 'packetsend' - Emitted when the client sends any packet (including publish and subscription packets).
+ * - 'packetreceive' - Emitted when the client receives any packet.
+ * - 'events' - Device sends events, passes (topic, payload).
+ * - 'status' - Device sends status, passes (topic, payload).
+ * - 'status-legacy' - Device sends legacy status with lifecycle events, passes (topic, payload).
+ * - 'response' - Device responds to commands, passes (topic, payload).
+ * - 'unknown' - Unknown message type received, passes (topic, payload).
  */
 export class YotoMqttClient extends EventEmitter {
+  /** @type {typeof commands} */ commands = commands
+  /** @type {MqttClient} */ mqttClient
+  /** @type {string} */ deviceId
+  /** @type {boolean} */ #autoSubscribe = true
+
   /**
    * Create a Yoto MQTT client
    * @param {MqttClient} mqttClient - Underlying MQTT client
@@ -281,13 +341,10 @@ export class YotoMqttClient extends EventEmitter {
 
     this.mqttClient = mqttClient
     this.deviceId = deviceId
-    this.autoSubscribe = options.autoSubscribe !== false
+    this.#autoSubscribe = options.autoSubscribe !== false
 
     // Bind MQTT event handlers
     this.#setupEventHandlers()
-
-    // Export command builders for convenience
-    this.commands = commands
   }
 
   /**
@@ -313,29 +370,44 @@ export class YotoMqttClient extends EventEmitter {
    */
   #setupEventHandlers () {
     // Connection established
-    this.mqttClient.on('connect', async () => {
-      // Auto-subscribe to device topics if enabled
-      if (this.autoSubscribe) {
-        await this.#subscribe()
-      }
+    this.mqttClient.on('connect', (connack) => {
+      this.emit('connect', connack)
 
-      // Only emit connected after subscriptions are ready
-      this.emit('connected')
+      // Auto-subscribe to device topics if enabled and no prior session
+      if (this.#autoSubscribe && !connack.sessionPresent) {
+        this.#subscribe().catch((error) => {
+          this.emit('error', error)
+        })
+      }
     })
 
     // Connection lost
-    this.mqttClient.on('disconnect', () => {
-      this.emit('disconnected')
+    this.mqttClient.on('disconnect', (packet) => {
+      /** @type {YotoMqttClientDisconnectMetadata} */
+      const metadata = { packet }
+      this.emit('disconnect', metadata)
     })
 
     // Connection closed
     this.mqttClient.on('close', () => {
-      this.emit('disconnected')
+      /** @type {YotoMqttClientCloseMetadata} */
+      const metadata = { reason: 'close' }
+      this.emit('close', metadata)
     })
 
     // Reconnecting
     this.mqttClient.on('reconnect', () => {
-      this.emit('reconnecting')
+      this.emit('reconnect')
+    })
+
+    // Client went offline
+    this.mqttClient.on('offline', () => {
+      this.emit('offline')
+    })
+
+    // Client end requested
+    this.mqttClient.on('end', () => {
+      this.emit('end')
     })
 
     // Error occurred
@@ -343,6 +415,16 @@ export class YotoMqttClient extends EventEmitter {
       this.emit('error', error)
     })
 
+    // Packet sent
+    this.mqttClient.on('packetsend', (packet) => {
+      this.emit('packetsend', packet)
+    })
+
+    // Packet received
+    this.mqttClient.on('packetreceive', (packet) => {
+      this.emit('packetreceive', packet)
+    })
+
     // Message received
     this.mqttClient.on('message', (topic, message) => {
       this.#handleMessage(topic, message)

package/lib/mqtt/factory.d.ts

@@ -10,7 +10,8 @@
  *
  * const client = createYotoMqttClient({
  *   deviceId: 'abc123',
- *   accessToken: 'eyJhbGc...'
+ *   token,
+ *   clientId: 'my-unique-client-id'
  * })
  *
  * client.on('events', (message) => {
@@ -25,7 +26,8 @@
  * // Disable automatic reconnection
  * const client = createYotoMqttClient({
  *   deviceId: 'abc123',
- *   accessToken: 'token',
+ *   token,
+ *   clientId: 'my-unique-client-id',
  *   mqttOptions: {
  *     reconnectPeriod: 0,     // Disable auto-reconnect (default is 5000ms)
  *     connectTimeout: 30000   // 30 second connection timeout
@@ -44,9 +46,13 @@ export type YotoMqttOptions = {
      */
     deviceId: string;
     /**
-     * - JWT access token for authentication
+     * - RefreshableToken instance used to supply the current JWT. Enables auto-updating auth on reconnect via transformWsUrl.
      */
-    accessToken: string;
+    token: RefreshableToken;
+    /**
+     * - Stable unique session ID suffix used to avoid collisions across multiple clients/processes. Used to build the MQTT clientId: DASH${deviceId}${sessionId} (non-alphanumeric characters are stripped). (MQTT calls this clientId, but we call it sessionId to not confuse it with the oauth clientId)
+     */
+    sessionId?: string;
     /**
      * - Prefix for MQTT client ID (default: 'DASH')
      */
@@ -64,10 +70,11 @@ export type YotoMqttOptions = {
      */
     autoSubscribe?: boolean;
     /**
-     * - Additional MQTT.js client options (defaults: reconnectPeriod=5000, keepalive=300; cannot override: clientId, username, password, protocol, ALPNProtocols)
+     * - Additional MQTT.js client options (defaults: reconnectPeriod=5000, reconnectOnConnackError=true, keepalive=300, clean=false; cannot override: clientId, username, password, protocol, ALPNProtocols; transformWsUrl is wrapped to keep auth current)
      */
     mqttOptions?: MqttClientOptions;
 };
 import { YotoMqttClient } from './client.js';
 import mqtt from 'mqtt';
+import type { RefreshableToken } from '../token.js';
 //# sourceMappingURL=factory.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["factory.js"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,8CAjCW,eAAe,GACb,cAAc,CAmF1B;;;;gCA/GY,OAAO,CAAC,mBAAc,CAAC;;;;;cAKtB,MAAM;;;;iBACN,MAAM;;;;qBACN,MAAM;;;;gBACN,MAAM;;;;WACN,MAAM;;;;oBACN,OAAO;;;;kBACP,iBAAiB;;+BAIA,aAAa;iBAD3B,MAAM"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["factory.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,8CAnCW,eAAe,GACb,cAAc,CA4G1B;;;;gCA1IY,OAAO,CAAC,mBAAc,CAAC;;;;;cAKtB,MAAM;;;;WACN,gBAAgB;;;;gBAChB,MAAM;;;;qBACN,MAAM;;;;gBACN,MAAM;;;;WACN,MAAM;;;;oBACN,OAAO;;;;kBACP,iBAAiB;;+BAIA,aAAa;iBAD3B,MAAM;sCAxBc,aAAa"}