mysa-js-sdk 1.3.3 → 2.0.0

package/dist/index.d.ts

@@ -20,6 +20,19 @@ declare class MysaApiError extends Error {
      */
     constructor(apiResponse: Response);
 }
+/** Error thrown when an MQTT publish ultimately fails after retry attempts. */
+declare class MqttPublishError extends Error {
+    attempts: number;
+    original?: unknown | undefined;
+    /**
+     * Creates a new MqttPublishError instance.
+     *
+     * @param message - A human-readable description of the publish failure.
+     * @param attempts - The number of attempts that were made before giving up.
+     * @param original - The original error object thrown by the underlying MQTT library (optional).
+     */
+    constructor(message: string, attempts: number, original?: unknown | undefined);
+}
 
 /**
  * Interface representing a temperature setpoint change event for a Mysa device.
@@ -43,7 +56,13 @@ interface SetPointChange {
  * Defines the possible operational states that a Mysa thermostat or heating device can be set to. These modes control
  * the device's heating behavior and power consumption.
  */
-type MysaDeviceMode = 'off' | 'heat';
+type MysaDeviceMode = 'off' | 'heat' | 'cool' | 'dry' | 'fan_only' | 'auto';
+/**
+ * Union type representing the available fan speed modes for Mysa devices.
+ *
+ * Defines the possible fan speed states that a Mysa thermostat device can be set to.
+ */
+type MysaFanSpeedMode = 'auto' | 'low' | 'medium' | 'high' | 'max';
 
 /**
  * Interface representing a device state change event for a Mysa device.
@@ -59,6 +78,8 @@ interface StateChange {
     mode?: MysaDeviceMode;
     /** Current temperature setpoint after the state change */
     setPoint: number;
+    /** Optional fan speed (1 = auto, 3 = low, 5 = medium, 7 = high, 8 = max). AC only */
+    fanSpeed?: MysaFanSpeedMode;
 }
 
 /**
@@ -155,9 +176,9 @@ interface BrandInfo {
     /** Unique identifier for the brand */
     Id: number;
     /** Remote control model number for the AC device */
-    remoteModelNumber: string;
+    remoteModelNumber?: string;
     /** Original Equipment Manufacturer brand name */
-    OEMBrand: string;
+    OEMBrand?: string;
 }
 /**
  * Supported capabilities and features for air conditioning devices.
@@ -198,55 +219,55 @@ interface ModeObj {
  */
 interface DeviceBase {
     /** Button digital input configuration value */
-    ButtonDI: number;
+    ButtonDI?: number;
     /** Maximum current rating as a string value */
-    MaxCurrent: string;
+    MaxCurrent?: string;
     /** Device model identifier string */
     Model: string;
     /** Button average value configuration */
-    ButtonAVE: number;
+    ButtonAVE?: number;
     /** Operating voltage of the device */
-    Voltage: number;
+    Voltage?: number;
     /** Button polling interval configuration */
-    ButtonPolling: number;
+    ButtonPolling?: number;
     /** Minimum brightness level (0-100) */
-    MinBrightness: number;
+    MinBrightness?: number;
     /** User-assigned device name */
-    Name: string;
+    Name?: string;
     /** Button low power mode configuration */
-    ButtonLowPower: number;
+    ButtonLowPower?: number;
     /** Type of heater controlled by the device */
-    HeaterType: string;
+    HeaterType?: string;
     /** Button repeat delay configuration in milliseconds */
-    ButtonRepeatDelay: number;
+    ButtonRepeatDelay?: number;
     /** Button repeat start delay configuration in milliseconds */
-    ButtonRepeatStart: number;
+    ButtonRepeatStart?: number;
     /** Display animation style setting */
-    Animation: string;
+    Animation?: string;
     /** Maximum brightness level (0-100) */
-    MaxBrightness: number;
+    MaxBrightness?: number;
     /** Array of user IDs allowed to control this device */
-    AllowedUsers: string[];
+    AllowedUsers?: string[];
     /** Current button state indicator */
-    ButtonState: string;
+    ButtonState?: string;
     /** Home identifier that this device belongs to */
-    Home: string;
+    Home?: string;
     /** Button sensitivity threshold configuration */
-    ButtonThreshold: number;
+    ButtonThreshold?: number;
     /** Data format version used by the device */
-    Format: string;
+    Format?: string;
     /** Time zone setting for the device */
-    TimeZone: string;
+    TimeZone?: string;
     /** Unix timestamp of when device was last paired */
-    LastPaired: number;
+    LastPaired?: number;
     /** Minimum temperature setpoint allowed */
-    MinSetpoint: number;
+    MinSetpoint?: number;
     /** Current operating mode of the device */
-    Mode: ModeObj;
+    Mode?: ModeObj;
     /** User ID of the device owner */
-    Owner: string;
+    Owner?: string;
     /** Maximum temperature setpoint allowed */
-    MaxSetpoint: number;
+    MaxSetpoint?: number;
     /** Unique device identifier */
     Id: string;
     /** Optional zone assignment for the device */
@@ -320,43 +341,45 @@ interface DeviceState {
     /** Overall timestamp for the device state */
     Timestamp: number;
     /** Time the device has been on */
-    OnTime: TimestampedValue<number>;
+    OnTime?: TimestampedValue<number>;
     /** Temperature set point */
-    SetPoint: TimestampedValue<number>;
+    SetPoint?: TimestampedValue<number>;
     /** Display brightness level */
-    Brightness: TimestampedValue<number>;
+    Brightness?: TimestampedValue<number>;
     /** Schedule mode setting */
-    ScheduleMode: TimestampedValue<number>;
+    ScheduleMode?: TimestampedValue<number>;
     /** Hold time setting */
-    HoldTime: TimestampedValue<number>;
+    HoldTime?: TimestampedValue<number>;
     /** Wi-Fi signal strength */
-    Rssi: TimestampedValue<number>;
+    Rssi?: TimestampedValue<number>;
     /** Thermostat mode */
-    TstatMode: TimestampedValue<number>;
+    TstatMode?: TimestampedValue<number>;
     /** Available heap memory */
-    FreeHeap: TimestampedValue<number>;
+    FreeHeap?: TimestampedValue<number>;
     /** Sensor temperature reading */
-    SensorTemp: TimestampedValue<number>;
+    SensorTemp?: TimestampedValue<number>;
     /** Current mode */
-    Mode: TimestampedValue<number>;
+    Mode?: TimestampedValue<number>;
     /** Voltage measurement */
-    Voltage: TimestampedValue<number>;
+    Voltage?: TimestampedValue<number>;
     /** Temperature corrected for calibration */
-    CorrectedTemp: TimestampedValue<number>;
+    CorrectedTemp?: TimestampedValue<number>;
     /** Duty cycle percentage */
-    Duty: TimestampedValue<number>;
+    Duty?: TimestampedValue<number>;
     /** Heat sink temperature */
-    HeatSink: TimestampedValue<number>;
+    HeatSink?: TimestampedValue<number>;
     /** Time the device has been off */
-    OffTime: TimestampedValue<number>;
+    OffTime?: TimestampedValue<number>;
     /** Connection status */
-    Connected: TimestampedValue<boolean>;
+    Connected?: TimestampedValue<boolean>;
     /** Current consumption */
-    Current: TimestampedValue<number>;
+    Current?: TimestampedValue<number>;
     /** Humidity reading */
-    Humidity: TimestampedValue<number>;
+    Humidity?: TimestampedValue<number>;
     /** Lock status */
-    Lock: TimestampedValue<number>;
+    Lock?: TimestampedValue<number>;
+    /** Fan speed */
+    FanSpeed?: TimestampedValue<number>;
 }
 /**
  * Collection of device states indexed by device ID
@@ -446,10 +469,12 @@ interface DeviceStateChange extends MsgPayload<OutMessageType.DEVICE_STATE_CHANG
             ho: number;
             /** Unknown */
             lk: number;
-            /** Device mode (1 = OFF, 3 = HEAT) */
+            /** Device mode (1 = OFF, 2 = AUTO, 3 = HEAT, 4 = COOL, 5 = FAN_ONLY, 6 = DRY) */
             md: number;
             /** Temperature setpoint */
             sp: number;
+            /** Optional fan speed (1 = auto, 3 = low, 5 = medium, 7 = high, 8 = max). AC only */
+            fn?: number;
         };
         /** Success indicator for the state change operation (1 = success, 0 = failure) */
         success: number;
@@ -670,6 +695,13 @@ interface MysaApiClientOptions {
     fetcher?: typeof fetch;
 }
 
+/** Options for MQTT publish operations. */
+interface MqttPublishOptions {
+    /** Maximum number of publish attempts before failing (default: 5). */
+    maxAttempts?: number;
+    /** Base delay in milliseconds used for exponential backoff calculation (default: 500). */
+    baseDelayMs?: number;
+}
 /**
  * Main client for interacting with the Mysa API and real-time device communication.
  *
@@ -831,15 +863,20 @@ declare class MysaApiClient {
      *
      * // Set temperature and mode
      * await client.setDeviceState('device123', 20, 'heat');
+     *
+     * // Set fan speed
+     * await client.setDeviceState('device123', undefined, undefined, 'auto');
      * ```
      *
      * @param deviceId - The ID of the device to control.
      * @param setPoint - The target temperature set point (optional).
-     * @param mode - The operating mode to set ('off', 'heat', or undefined to leave unchanged).
+     * @param mode - The operating mode to set (one of MysaDeviceMode values, or undefined to leave unchanged).
+     * @param fanSpeed - The fan speed mode to set ('low', 'medium', 'high', 'max', 'auto', or undefined to leave
+     *   unchanged).
      * @throws {@link UnauthenticatedError} When the user is not authenticated.
      * @throws {@link Error} When MQTT connection or command sending fails.
      */
-    setDeviceState(deviceId: string, setPoint?: number, mode?: MysaDeviceMode): Promise<void>;
+    setDeviceState(deviceId: string, setPoint?: number, mode?: MysaDeviceMode, fanSpeed?: MysaFanSpeedMode): Promise<void>;
     /**
      * Starts receiving real-time updates for the specified device.
      *
@@ -881,7 +918,7 @@ declare class MysaApiClient {
      * @returns A promise that resolves to a valid CognitoUserSession.
      * @throws {@link UnauthenticatedError} When no session exists or refresh fails.
      */
-    private getFreshSession;
+    private _getFreshSession;
     /**
      * Establishes and returns an MQTT connection for real-time communication.
      *
@@ -891,14 +928,49 @@ declare class MysaApiClient {
      * @returns A promise that resolves to an active MQTT connection.
      * @throws {@link Error} When connection establishment fails.
      */
-    private getMqttConnection;
+    private _getMqttConnection;
+    /**
+     * Determines whether an MQTT-related error is considered transient and worth retrying.
+     *
+     * Transient errors include timeouts, cancelled operations due to clean sessions, temporary connectivity loss, and
+     * other recoverable network issues. Fatal errors (auth, permission, configuration) should not be retried at this
+     * layer.
+     *
+     * @param err - The error object thrown by the underlying MQTT operation.
+     * @returns True if the error appears transient and a retry should be attempted; false otherwise.
+     */
+    private _isTransientMqttError;
+    /**
+     * Publishes an MQTT message with exponential backoff retries for transient failures.
+     *
+     * Retries occur for errors classified by `_isTransientMqttError`. Between attempts the delay grows exponentially with
+     * jitter to avoid thundering herds after broker recovery. If the connection is not currently marked as connected, a
+     * reconnect is attempted; if that fails, the connection is rebuilt (fresh credentials) before the next retry.
+     *
+     * On final failure (after maxAttempts) a {@link MqttPublishError} is thrown including the number of attempts and
+     * original error for higher-level handling.
+     *
+     * @remarks
+     * Retry options fields:
+     *
+     * - MaxAttempts: Maximum number of publish attempts before failing (default: 5).
+     * - BaseDelayMs: Base delay in milliseconds used for exponential backoff calculation (default: 500).
+     *
+     * @param connection - The active MQTT client connection used to send the publish.
+     * @param topic - The MQTT topic to publish to.
+     * @param payload - The serialized payload (binary buffer or Uint8Array).
+     * @param qos - The desired MQTT QoS level for the publish.
+     * @param opts - Retry options (defaults: maxAttempts=5, baseDelayMs=500).
+     * @returns A promise that resolves when the publish succeeds, or rejects with {@link MqttPublishError}.
+     */
+    private _publishWithRetry;
     /**
      * Creates a new MQTT connection using AWS IoT WebSocket connections with Cognito credentials.
      *
      * @returns A promise that resolves to an active MQTT connection.
      * @throws {@link Error} When connection establishment fails.
      */
-    private createMqttConnection;
+    private _createMqttConnection;
     /**
      * Processes incoming MQTT messages and emits appropriate events.
      *
@@ -908,7 +980,7 @@ declare class MysaApiClient {
      *
      * @param payload - The raw MQTT message payload to process.
      */
-    private processMqttMessage;
+    private _processMqttMessage;
 }
 
 /**
@@ -961,6 +1033,8 @@ interface ChangeDeviceState extends MsgPayload<InMessageType.CHANGE_DEVICE_STATE
                 md?: number;
                 /** Unknown, should always be -1 */
                 tm: number;
+                /** Optional fan speed (1 = auto, 3 = low, 5 = medium, 7 = high, 8 = max). AC only */
+                fn?: number;
             }
         ];
         /**
@@ -1019,4 +1093,4 @@ type MsgTypeInPayload = CheckDeviceSettings | StartPublishingDeviceStatus;
  */
 type InPayload = MsgTypeInPayload | MsgInPayload;
 
-export { type BrandInfo, type ChangeDeviceState, type CheckDeviceSettings, type DeviceBase, type DeviceLog, type DevicePostBoot, type DeviceSetpointChange, type DeviceState, type DeviceStateChange, type DeviceStates, type DeviceStatesObj, type DeviceV1Status, type DeviceV2Status, type Devices, type DevicesObj, type FirmwareDevice, type Firmwares, InMessageType, type InPayload, type Logger, type ModeObj, type MsgBasePayload, type MsgInPayload, type MsgOutPayload, type MsgPayload, type MsgTypeBasePayload, type MsgTypeInPayload, type MsgTypeOutPayload, type MsgTypePayload, MysaApiClient, type MysaApiClientEventTypes, type MysaApiClientOptions, MysaApiError, type MysaDeviceMode, type MysaSession, OutMessageType, type OutPayload, type SetPointChange, type StartPublishingDeviceStatus, type StateChange, type Status, type SupportedCaps, type TimestampedValue, UnauthenticatedError, VoidLogger };
+export { type BrandInfo, type ChangeDeviceState, type CheckDeviceSettings, type DeviceBase, type DeviceLog, type DevicePostBoot, type DeviceSetpointChange, type DeviceState, type DeviceStateChange, type DeviceStates, type DeviceStatesObj, type DeviceV1Status, type DeviceV2Status, type Devices, type DevicesObj, type FirmwareDevice, type Firmwares, InMessageType, type InPayload, type Logger, type ModeObj, MqttPublishError, type MqttPublishOptions, type MsgBasePayload, type MsgInPayload, type MsgOutPayload, type MsgPayload, type MsgTypeBasePayload, type MsgTypeInPayload, type MsgTypeOutPayload, type MsgTypePayload, MysaApiClient, type MysaApiClientEventTypes, type MysaApiClientOptions, MysaApiError, type MysaDeviceMode, type MysaFanSpeedMode, type MysaSession, OutMessageType, type OutPayload, type SetPointChange, type StartPublishingDeviceStatus, type StateChange, type Status, type SupportedCaps, type TimestampedValue, UnauthenticatedError, VoidLogger };