yoto-nodejs-client 0.0.1 → 0.0.2

package/lib/mqtt/factory.d.ts

@@ -1,11 +1,54 @@
+/**
+ * Create a configured MQTT client for a Yoto device
+ * @param {YotoMqttOptions} options - MQTT connection options
+ * @returns {YotoMqttClient} Configured Yoto MQTT client
+ * @throws {Error} If required options are missing
+ *
+ * @example
+ * ```javascript
+ * import { createYotoMqttClient } from 'yoto-nodejs-client/lib/mqtt'
+ *
+ * const client = createYotoMqttClient({
+ *   deviceId: 'abc123',
+ *   accessToken: 'eyJhbGc...'
+ * })
+ *
+ * client.on('events', (message) => {
+ *   console.log('Playing:', message.trackTitle)
+ * })
+ *
+ * await client.connect()
+ * ```
+ */
 export function createYotoMqttClient(options: YotoMqttOptions): YotoMqttClient;
 export type YotoMqttOptions = {
+    /**
+     * - Device ID to connect to
+     */
     deviceId: string;
+    /**
+     * - JWT access token for authentication
+     */
     accessToken: string;
+    /**
+     * - Prefix for MQTT client ID (default: 'DASH')
+     */
     clientIdPrefix?: string;
+    /**
+     * - MQTT broker URL
+     */
     brokerUrl?: string;
+    /**
+     * - Keepalive interval in seconds
+     */
     keepalive?: number;
+    /**
+     * - MQTT broker port
+     */
     port?: number;
+    /**
+     * - Auto-subscribe to device topics on connect
+     */
     autoSubscribe?: boolean;
 };
 import { YotoMqttClient } from './client.js';

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

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["factory.js"],"names":[],"mappings":"AA2DA,8CApBW,eAAe,GACb,cAAc,CAkE1B;;cAzFa,MAAM;iBACN,MAAM;qBACN,MAAM;gBACN,MAAM;gBACN,MAAM;WACN,MAAM;oBACN,OAAO;;+BAIU,aAAa"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["factory.js"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8CApBW,eAAe,GACb,cAAc,CAkE1B;;;;;cAzFa,MAAM;;;;iBACN,MAAM;;;;qBACN,MAAM;;;;gBACN,MAAM;;;;gBACN,MAAM;;;;WACN,MAAM;;;;oBACN,OAAO;;+BAIU,aAAa"}

package/lib/mqtt/topics.d.ts

@@ -1,34 +1,191 @@
+/**
+ * Get the events topics for a device (both old and new formats)
+ * Devices publish to both paths, so both are returned
+ * @param {string} deviceId - Device ID
+ * @returns {string[]} Events topics [old format, new format]
+ */
 export function getEventsTopic(deviceId: string): string[];
+/**
+ * Get the status topics for a device (both old and new formats)
+ * Devices publish to both paths, so both are returned
+ * @param {string} deviceId - Device ID
+ * @returns {string[]} Status topics [old format, new format]
+ */
 export function getStatusTopic(deviceId: string): string[];
+/**
+ * Get the response topic for a device (subscribe)
+ * @param {string} deviceId - Device ID
+ * @returns {string} Response topic
+ */
 export function getResponseTopic(deviceId: string): string;
+/**
+ * Get all subscription topics for a device
+ *
+ * Subscribes to both old and new topic formats because Yoto devices publish to both:
+ * - Old format: device/{id}/events, device/{id}/status
+ * - New format: device/{id}/data/events, device/{id}/data/status
+ *
+ * This ensures all messages are received regardless of which path the device uses.
+ *
+ * @param {string} deviceId - Device ID
+ * @returns {string[]} Array of topics to subscribe to (includes both old and new formats)
+ */
 export function getSubscriptionTopics(deviceId: string): string[];
+/**
+ * Get a command topic for a device (publish)
+ * @param {string} deviceId - Device ID
+ * @param {string} resource - Command resource (e.g., 'volume', 'ambients', 'card')
+ * @param {string} [action] - Command action (e.g., 'set', 'start', 'stop')
+ * @returns {string} Command topic
+ */
 export function getCommandTopic(deviceId: string, resource: string, action?: string): string;
+/**
+ * Parse a topic string to extract device ID and message type
+ * @param {string} topic - Full MQTT topic string
+ * @returns {{ deviceId: string, messageType: YotoMqttTopicType | 'unknown' }} Parsed topic info
+ */
 export function parseTopic(topic: string): {
     deviceId: string;
     messageType: YotoMqttTopicType | "unknown";
 };
+/**
+ * Get the events request command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Events request topic
+ */
 export function getEventsRequestTopic(deviceId: string): string;
+/**
+ * Get the status request command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Status request topic
+ */
 export function getStatusRequestTopic(deviceId: string): string;
+/**
+ * Get the volume set command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Volume set topic
+ */
 export function getVolumeSetTopic(deviceId: string): string;
+/**
+ * Get the ambients set command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Ambients set topic
+ */
 export function getAmbientsSetTopic(deviceId: string): string;
+/**
+ * Get the sleep timer set command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Sleep timer set topic
+ */
 export function getSleepTimerSetTopic(deviceId: string): string;
+/**
+ * Get the reboot command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Reboot topic
+ */
 export function getRebootTopic(deviceId: string): string;
+/**
+ * Get the card start command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Card start topic
+ */
 export function getCardStartTopic(deviceId: string): string;
+/**
+ * Get the card stop command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Card stop topic
+ */
 export function getCardStopTopic(deviceId: string): string;
+/**
+ * Get the card pause command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Card pause topic
+ */
 export function getCardPauseTopic(deviceId: string): string;
+/**
+ * Get the card resume command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Card resume topic
+ */
 export function getCardResumeTopic(deviceId: string): string;
+/**
+ * Get the bluetooth on command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth on topic
+ */
 export function getBluetoothOnTopic(deviceId: string): string;
+/**
+ * Get the bluetooth off command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth off topic
+ */
 export function getBluetoothOffTopic(deviceId: string): string;
+/**
+ * Get the bluetooth delete bonds command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth delete bonds topic
+ */
 export function getBluetoothDeleteBondsTopic(deviceId: string): string;
+/**
+ * Get the bluetooth connect command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth connect topic
+ */
 export function getBluetoothConnectTopic(deviceId: string): string;
+/**
+ * Get the bluetooth disconnect command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth disconnect topic
+ */
 export function getBluetoothDisconnectTopic(deviceId: string): string;
+/**
+ * Get the bluetooth state command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Bluetooth state topic
+ */
 export function getBluetoothStateTopic(deviceId: string): string;
+/**
+ * Get the display preview command topic
+ * @param {string} deviceId - Device ID
+ * @returns {string} Display preview topic
+ */
 export function getDisplayPreviewTopic(deviceId: string): string;
+/**
+ * MQTT Topics for Yoto Players
+ *
+ * Topic builders and constants for Yoto MQTT communication
+ * @see https://yoto.dev/players-mqtt/
+ */
+/**
+ * MQTT topic type for subscriptions
+ * @typedef {'events' | 'status' | 'response'} YotoMqttTopicType
+ */
+/**
+ * MQTT broker URL for Yoto devices
+ */
 export const MQTT_BROKER_URL: "wss://aqrphjqbp3u2z-ats.iot.eu-west-2.amazonaws.com";
+/**
+ * MQTT authorizer name for Yoto authentication
+ */
 export const MQTT_AUTH_NAME: "PublicJWTAuthorizer";
+/**
+ * MQTT connection port
+ */
 export const MQTT_PORT: 443;
+/**
+ * MQTT protocol
+ */
 export const MQTT_PROTOCOL: "wss";
+/**
+ * MQTT keepalive interval in seconds
+ */
 export const MQTT_KEEPALIVE: 300;
+/**
+ * ALPN protocols for AWS IoT
+ */
 export const MQTT_ALPN_PROTOCOLS: string[];
+/**
+ * MQTT topic type for subscriptions
+ */
 export type YotoMqttTopicType = "events" | "status" | "response";
 //# sourceMappingURL=topics.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"topics.d.ts","sourceRoot":"","sources":["topics.js"],"names":[],"mappings":"AAoDA,yCAHW,MAAM,GACJ,MAAM,EAAE,CAOpB;AAQD,yCAHW,MAAM,GACJ,MAAM,EAAE,CAOpB;AAOD,2CAHW,MAAM,GACJ,MAAM,CAIlB;AAcD,gDAHW,MAAM,GACJ,MAAM,EAAE,CAQpB;AASD,0CALW,MAAM,YACN,MAAM,WACN,MAAM,GACJ,MAAM,CAKlB;AAOD,kCAHW,MAAM,GACJ;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAAE,CAuB5E;AASD,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,8CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,yCAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,2CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,6CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,8CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,+CAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,uDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,mDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,sDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,iDAHW,MAAM,GACJ,MAAM,CAIlB;AAOD,iDAHW,MAAM,GACJ,MAAM,CAIlB;AAnRD,8BAA+B,qDAAqD,CAAA;AAKpF,6BAA8B,qBAAqB,CAAA;AAKnD,wBAAyB,GAAG,CAAA;AAK5B,4BAA6B,KAAK,CAAA;AAKlC,6BAA8B,GAAG,CAAA;AAKjC,2CAAqD;gCA/BxC,QAAQ,GAAG,QAAQ,GAAG,UAAU"}
+{"version":3,"file":"topics.d.ts","sourceRoot":"","sources":["topics.js"],"names":[],"mappings":"AA8CA;;;;;GAKG;AACH,yCAHW,MAAM,GACJ,MAAM,EAAE,CAOpB;AAED;;;;;GAKG;AACH,yCAHW,MAAM,GACJ,MAAM,EAAE,CAOpB;AAED;;;;GAIG;AACH,2CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;GAWG;AACH,gDAHW,MAAM,GACJ,MAAM,EAAE,CAQpB;AAED;;;;;;GAMG;AACH,0CALW,MAAM,YACN,MAAM,WACN,MAAM,GACJ,MAAM,CAKlB;AAED;;;;GAIG;AACH,kCAHW,MAAM,GACJ;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAAE,CAuB5E;AAID;;;;GAIG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,8CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,yCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,2CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,6CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,8CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,+CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,uDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,mDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,sDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,iDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;GAIG;AACH,iDAHW,MAAM,GACJ,MAAM,CAIlB;AAtSD;;;;;GAKG;AAMH;;;GAGG;AAEH;;GAEG;AACH,8BAA+B,qDAAqD,CAAA;AAEpF;;GAEG;AACH,6BAA8B,qBAAqB,CAAA;AAEnD;;GAEG;AACH,wBAAyB,GAAG,CAAA;AAE5B;;GAEG;AACH,4BAA6B,KAAK,CAAA;AAElC;;GAEG;AACH,6BAA8B,GAAG,CAAA;AAEjC;;GAEG;AACH,2CAAqD;;;;gCA/BxC,QAAQ,GAAG,QAAQ,GAAG,UAAU"}

package/lib/token.d.ts

@@ -1,24 +1,112 @@
+/**
+ * @typedef {Object} RefreshableTokenOpts
+ * @property {string} clientId - OAuth client ID
+ * @property {string} refreshToken - OAuth refresh token
+ * @property {string} accessToken - Initial OAuth access token (JWT)
+ * @property {number} [bufferSeconds=30] - Seconds before expiration to consider token expired
+ */
+/**
+ * @typedef {Object} RefreshSuccessEvent
+ * @property {string} clientId - The OAuth client ID
+ * @property {string} accessToken - The new access token
+ * @property {string} refreshToken - The refresh token (may be updated)
+ * @property {number} expiresAt - Unix timestamp in seconds when token expires
+ */
+/**
+ * Event map for RefreshableToken
+ * @typedef {{
+ *   'refresh:start': [],
+ *   'refresh:success': [RefreshSuccessEvent],
+ *   'refresh:error': [Error],
+ *   'invalid': [Error]
+ * }} RefreshableTokenEventMap
+ */
+/**
+ * A refreshable OAuth token that automatically refreshes when expired.
+ * Handles in-flight refresh deduplication to prevent multiple concurrent refresh requests.
+ *
+ * Events:
+ * - 'refresh:start' - Emitted when token refresh begins
+ * - 'refresh:success' - Emitted when token refresh succeeds, passes { clientId, accessToken, refreshToken, expiresAt }
+ * - 'refresh:error' - Emitted when token refresh fails (transient errors), passes error
+ * - 'invalid' - Emitted when refresh token is permanently invalid, passes error
+ *
+ * @extends {EventEmitter<RefreshableTokenEventMap>}
+ */
 export class RefreshableToken extends EventEmitter<RefreshableTokenEventMap> {
+    /**
+     * @param {RefreshableTokenOpts} opts
+     */
     constructor({ clientId, refreshToken, accessToken, bufferSeconds }: RefreshableTokenOpts);
+    /**
+     * Get a valid access token, refreshing if necessary.
+     * @returns {Promise<string>} Valid access token
+     * @throws {Error} If token is invalid or refresh fails
+     */
     getAccessToken(): Promise<string>;
+    /**
+     * Check if the token is currently valid (not expired and not marked invalid).
+     * @returns {boolean} True if token is valid
+     */
     isValid(): boolean;
+    /**
+     * Get the expiration timestamp of the current access token.
+     * @returns {number} Unix timestamp (seconds since epoch)
+     */
     getExpiresAt(): number;
+    /**
+     * Get the time remaining until token expiration.
+     * @returns {number} Seconds until expiration (may be negative if expired)
+     */
     getTimeRemaining(): number;
+    /**
+     * Manually trigger a token refresh, regardless of expiration status.
+     * Useful for proactive refresh or testing.
+     * @returns {Promise<RefreshSuccessEvent>} Token information including clientId, accessToken, refreshToken, and expiresAt
+     * @throws {Error} If token is invalid or refresh fails
+     */
     refresh(): Promise<RefreshSuccessEvent>;
     #private;
 }
 export type RefreshableTokenOpts = {
+    /**
+     * - OAuth client ID
+     */
     clientId: string;
+    /**
+     * - OAuth refresh token
+     */
     refreshToken: string;
+    /**
+     * - Initial OAuth access token (JWT)
+     */
     accessToken: string;
+    /**
+     * - Seconds before expiration to consider token expired
+     */
     bufferSeconds?: number;
 };
 export type RefreshSuccessEvent = {
+    /**
+     * - The OAuth client ID
+     */
     clientId: string;
+    /**
+     * - The new access token
+     */
     accessToken: string;
+    /**
+     * - The refresh token (may be updated)
+     */
     refreshToken: string;
+    /**
+     * - Unix timestamp in seconds when token expires
+     */
     expiresAt: number;
 };
+/**
+ * Event map for RefreshableToken
+ */
 export type RefreshableTokenEventMap = {
     "refresh:start": [];
     "refresh:success": [RefreshSuccessEvent];

package/lib/token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["token.js"],"names":[],"mappings":"AA0CA;IAmBE,oEAFW,oBAAoB,EAoB9B;IAOD,kBAHa,OAAO,CAAC,MAAM,CAAC,CAiB3B;IA4FD,WAFa,OAAO,CASnB;IAMD,gBAFa,MAAM,CAIlB;IAMD,oBAFa,MAAM,CAKlB;IAQD,WAHa,OAAO,CAAC,mBAAmB,CAAC,CAiBxC;;CACF;;cAzOa,MAAM;kBACN,MAAM;iBACN,MAAM;oBACN,MAAM;;;cAKN,MAAM;iBACN,MAAM;kBACN,MAAM;eACN,MAAM;;uCAKP;IACZ,eAAmB,EAAE,EAAE,CAAC;IACxB,iBAAqB,EAAE,CAAC,mBAAmB,CAAC,CAAC;IAC7C,eAAmB,EAAE,CAAC,KAAK,CAAC,CAAC;IAC7B,SAAa,EAAE,CAAC,KAAK,CAAC,CAAA;CACnB;6BA3ByB,aAAa"}
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["token.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH;;;;;;GAMG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH;IAgBE;;OAEG;IACH,oEAFW,oBAAoB,EAoB9B;IAED;;;;OAIG;IACH,kBAHa,OAAO,CAAC,MAAM,CAAC,CAiB3B;IAwFD;;;OAGG;IACH,WAFa,OAAO,CASnB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAFa,MAAM,CAKlB;IAED;;;;;OAKG;IACH,WAHa,OAAO,CAAC,mBAAmB,CAAC,CAiBxC;;CACF;;;;;cAzOa,MAAM;;;;kBACN,MAAM;;;;iBACN,MAAM;;;;oBACN,MAAM;;;;;;cAKN,MAAM;;;;iBACN,MAAM;;;;kBACN,MAAM;;;;eACN,MAAM;;;;;uCAKP;IACZ,eAAmB,EAAE,EAAE,CAAC;IACxB,iBAAqB,EAAE,CAAC,mBAAmB,CAAC,CAAC;IAC7C,eAAmB,EAAE,CAAC,KAAK,CAAC,CAAC;IAC7B,SAAa,EAAE,CAAC,KAAK,CAAC,CAAA;CACnB;6BA3ByB,aAAa"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.1",
+  "version": "0.0.2",
   "author": "Bret Comnes <bcomnes@gmail.com> (https://bret.io)",
   "bugs": {
     "url": "https://github.com/bcomnes/yoto-nodejs-client/issues"