mysa-js-sdk 2.1.2 → 3.1.0

package/dist/index.d.cts

@@ -1,11 +1,20 @@
 /** Error thrown when attempting to access the Mysa API without proper authentication. */
 declare class UnauthenticatedError extends Error {
+    /**
+     * The underlying failure that prevented authentication.
+     *
+     * Callers need it to tell a credential rejection apart from a transport or service failure, since both surface as
+     * this error. Declared explicitly rather than passed to `super` so the SDK keeps compiling against its current lib,
+     * which predates the two-argument `Error` constructor.
+     */
+    readonly cause?: unknown;
     /**
      * Creates a new UnauthenticatedError instance.
      *
      * @param message - The error message
+     * @param cause - The underlying failure that prevented authentication, if any.
      */
-    constructor(message: string);
+    constructor(message: string, cause?: unknown);
 }
 /** Error thrown when a Mysa API request fails. */
 declare class MysaApiError extends Error {
@@ -20,6 +29,30 @@ declare class MysaApiError extends Error {
      */
     constructor(apiResponse: Response);
 }
+/** Error thrown when a device id does not match any device on the account. */
+declare class UnknownDeviceError extends Error {
+    readonly deviceId: string;
+    /**
+     * Creates a new UnknownDeviceError instance.
+     *
+     * @param deviceId - The device id that could not be resolved
+     */
+    constructor(deviceId: string);
+}
+/** Error thrown when a requested fan speed is not supported by the target device. */
+declare class UnsupportedFanSpeedError extends Error {
+    readonly deviceId: string;
+    readonly fanSpeed: string;
+    readonly supportedFanSpeeds: string[];
+    /**
+     * Creates a new UnsupportedFanSpeedError instance.
+     *
+     * @param deviceId - The id of the device the command was aimed at.
+     * @param fanSpeed - The requested fan speed that the device does not support.
+     * @param supportedFanSpeeds - The fan speeds the device does support.
+     */
+    constructor(deviceId: string, fanSpeed: string, supportedFanSpeeds: string[]);
+}
 /** Error thrown when an MQTT publish ultimately fails after retry attempts. */
 declare class MqttPublishError extends Error {
     attempts: number;
@@ -99,8 +132,10 @@ interface Status {
     setPoint: number;
     /** Optional electrical current draw measurement in amperes */
     current?: number;
-    /** Optional heating element duty cycle as a percentage (0-100) */
+    /** Optional heating element duty cycle, as a fraction between 0.0 and 1.0 */
     dutyCycle?: number;
+    /** Optional floor-probe temperature reading, reported only by in-floor heating thermostats (INF-V1-0) */
+    floorTemperature?: number;
 }
 
 /** Interface for logging operations at different severity levels */
@@ -123,20 +158,16 @@ declare class VoidLogger implements Logger {
 }
 
 /**
- * Interface representing an authenticated Mysa user session.
+ * Interface representing the credentials of a Mysa account.
  *
- * Contains the authentication tokens and user information required to make authorized API calls to the Mysa service.
- * These tokens are typically obtained through the login process and used for subsequent API requests.
+ * The client authenticates with these credentials on demand, and re-authenticates with them whenever its session can no
+ * longer be refreshed. They are held for the lifetime of the client.
  */
-interface MysaSession {
-    /** The username/email address of the authenticated user */
+interface MysaCredentials {
+    /** The email address of the Mysa account. */
     username: string;
-    /** JWT identity token containing user identity information */
-    idToken: string;
-    /** JWT access token used for authorizing API requests */
-    accessToken: string;
-    /** JWT refresh token used to obtain new access tokens when they expire */
-    refreshToken: string;
+    /** The password of the Mysa account. */
+    password: string;
 }
 
 /**
@@ -200,6 +231,12 @@ interface SupportedCaps {
     version: string;
     /** Array of supported remote control key codes */
     keys: number[];
+    /**
+     * Optional device-specific fan-speed `fn` values, ordered by canonical fan speed (`[auto, low, medium, high, max]`).
+     * E.g. `[1, 2, 4, 6]` for CodeNum=1117 devices means auto=1, low=2, medium=4, high=6. When absent, a legacy universal
+     * mapping is assumed.
+     */
+    fanSpeeds?: number[];
 }
 /**
  * Device operating mode information.
@@ -553,12 +590,29 @@ interface DeviceV2Status extends MsgPayload<OutMessageType.DEVICE_V2_STATUS> {
     body: {
         /** Ambient temperature reading from the device sensor */
         ambTemp: number;
-        /** Current duty cycle percentage of the heating element */
-        dtyCycle: number;
+        /**
+         * Current duty cycle of the heating element, as a fraction between 0.0 and 1.0. Reported by baseboard V2 devices;
+         * absent on in-floor heating thermostats (INF-V1-0), which report {@link heatStat} instead.
+         */
+        dtyCycle?: number;
         /** Relative humidity percentage reading from the device sensor */
         hum: number;
         /** Current temperature setpoint setting */
         stpt: number;
+        /**
+         * Binary heating-relay state (0 = off, 1 = energized) reported by in-floor heating thermostats (INF-V1-0) in place
+         * of {@link dtyCycle}. Absent on baseboard V2 devices.
+         */
+        heatStat?: number;
+        /** Floor-probe temperature reading (°C) from in-floor heating thermostats. Absent on baseboard V2 devices. */
+        flrSnsrTemp?: number;
+        /**
+         * Which sensor the in-floor thermostat regulates against (3 = floor probe, 5 = ambient air). Absent on baseboard V2
+         * devices.
+         */
+        trackedSnsr?: number;
+        /** Line voltage (V) reported by in-floor heating thermostats. Absent on baseboard V2 devices. */
+        lineVtg?: number;
     };
 }
 
@@ -682,14 +736,6 @@ type OutPayload = MsgTypeOutPayload | MsgOutPayload;
  * emission in the Mysa API client's event system.
  */
 type MysaApiClientEventTypes = {
-    /**
-     * Event emitted when the session changes.
-     *
-     * @remarks
-     * You should subscribe to this event and persist the session object whenever it changes.
-     * @param session - The new session object or undefined if session was cleared.
-     */
-    sessionChanged: [session: MysaSession | undefined];
     /**
      * Event emitted when a device's status information is updated.
      *
@@ -761,9 +807,9 @@ interface MqttPublishOptions {
  * @example
  *
  * ```typescript
- * const client = new MysaApiClient();
+ * const client = new MysaApiClient({ username: 'user@example.com', password: 'password' });
  *
- * await client.login('user@example.com', 'password');
+ * await client.login();
  * const devices = await client.getDevices();
  *
  * client.emitter.on('statusChanged', (status) => {
@@ -776,10 +822,14 @@ interface MqttPublishOptions {
  * ```
  */
 declare class MysaApiClient {
+    /** The credentials of the Mysa account this client authenticates as. */
+    private _credentials;
     /** The current session object, if any. */
     private _cognitoUserSession?;
     /** The current user object, if any. */
     private _cognitoUser?;
+    /** The in-flight session acquisition, if any, so that concurrent callers share a single refresh or login. */
+    private _freshSessionPromise?;
     /** The logger instance used by the client. */
     private _logger;
     /** The fetcher function used by the client. */
@@ -794,8 +844,21 @@ declare class MysaApiClient {
     private _mqttInterrupts;
     /** Whether a forced MQTT reset is currently in progress (guards against re-entrancy). */
     private _mqttResetInProgress;
+    /** Monotonic id of the current MQTT connection; used to ignore events from discarded connections. */
+    private _mqttGeneration;
+    /** Consecutive forced resets without an intervening stable period; drives reset backoff. */
+    private _mqttConsecutiveResets;
+    /** Timestamp (ms) of the most recent successful MQTT (re)connect, for interrupt dwell-time diagnostics. */
+    private _mqttLastConnectionSuccessAt?;
+    /** Timer that clears the consecutive-reset counter once a connection stays healthy. */
+    private _mqttStabilityTimer?;
     /** The device IDs that are currently being updated in real-time, mapped to their respective timeouts. */
     private _realtimeDeviceIds;
+    /**
+     * Raw topic filters registered via {@link startRawTopicCapture}, mapped to their message handlers. Re-subscribed on
+     * every reconnect so a debug capture survives connection resets.
+     */
+    private _rawTopicCaptures;
     /** The cached devices object, if any. */
     private _cachedDevices?;
     /**
@@ -804,47 +867,41 @@ declare class MysaApiClient {
      * @see {@link MysaApiClientEventTypes} for the possible events and their payloads.
      */
     readonly emitter: EventEmitter<MysaApiClientEventTypes>;
-    /**
-     * Gets the persistable session object.
-     *
-     * @returns The current persistable session object, if any.
-     */
-    get session(): MysaSession | undefined;
-    /**
-     * Returns whether the client currently has an active session.
-     *
-     * @returns True if the client has an active session, false otherwise.
-     */
-    get isAuthenticated(): boolean;
     /**
      * Constructs a new instance of the MysaApiClient.
      *
-     * @param session - The persistable session object, if any.
+     * @param credentials - The credentials of the Mysa account to authenticate as.
      * @param options - The options for the client.
      */
-    constructor(session?: MysaSession, options?: MysaApiClientOptions);
+    constructor(credentials: MysaCredentials, options?: MysaApiClientOptions);
     /**
-     * Logs in the user with the given email address and password.
+     * Ensures the client has a usable session, logging in with the credentials it was constructed with if needed.
      *
-     * This method authenticates the user with Mysa's Cognito user pool and establishes a session that can be used for
-     * subsequent API calls. Upon successful login, a 'sessionChanged' event is emitted.
+     * Calling this method is optional: the client authenticates on demand before its first API call, and re-authenticates
+     * on its own whenever its session can no longer be refreshed. Call it explicitly at startup to fail fast on invalid
+     * credentials instead of on the first API call. It is a no-op when the current session is still usable.
      *
      * @example
      *
      * ```typescript
      * try {
-     *   await client.login('user@example.com', 'password123');
+     *   await client.login();
      *   console.log('Login successful!');
      * } catch (error) {
      *   console.error('Login failed:', error.message);
      * }
      * ```
      *
-     * @param emailAddress - The email address of the user.
-     * @param password - The password of the user.
+     * @throws {@link UnauthenticatedError} When authentication fails due to invalid credentials or network issues.
+     */
+    login(): Promise<void>;
+    /**
+     * Authenticates with Mysa's Cognito user pool and replaces the current session, if any.
+     *
+     * @returns A promise that resolves to the newly established session.
      * @throws {@link Error} When authentication fails due to invalid credentials or network issues.
      */
-    login(emailAddress: string, password: string): Promise<void>;
+    private _login;
     /**
      * Retrieves the list of devices associated with the user.
      *
@@ -862,7 +919,7 @@ declare class MysaApiClient {
      *
      * @returns A promise that resolves to the list of devices.
      * @throws {@link MysaApiError} When the API request fails.
-     * @throws {@link UnauthenticatedError} When the user is not authenticated.
+     * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
      */
     getDevices(): Promise<Devices>;
     /**
@@ -884,7 +941,7 @@ declare class MysaApiClient {
      *
      * @param deviceId - The ID of the device to get the serial number for.
      * @returns A promise that resolves to the serial number, or undefined if not found.
-     * @throws {@link UnauthenticatedError} When the user is not authenticated.
+     * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
      */
     getDeviceSerialNumber(deviceId: string): Promise<string | undefined>;
     /**
@@ -892,7 +949,7 @@ declare class MysaApiClient {
      *
      * @returns A promise that resolves to the firmware information for all devices.
      * @throws {@link MysaApiError} When the API request fails.
-     * @throws {@link UnauthenticatedError} When the user is not authenticated.
+     * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
      */
     getDeviceFirmwares(): Promise<Firmwares>;
     /**
@@ -900,7 +957,7 @@ declare class MysaApiClient {
      *
      * @returns A promise that resolves to the current state of all devices.
      * @throws {@link MysaApiError} When the API request fails.
-     * @throws {@link UnauthenticatedError} When the user is not authenticated.
+     * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
      */
     getDeviceStates(): Promise<DeviceStates>;
     /**
@@ -908,7 +965,7 @@ declare class MysaApiClient {
      *
      * @returns A promise that resolves to the homes information.
      * @throws {@link MysaApiError} When the API request fails.
-     * @throws {@link UnauthenticatedError} When the user is not authenticated.
+     * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
      */
     getHomes(): Promise<Homes>;
     /**
@@ -938,7 +995,9 @@ declare class MysaApiClient {
      * @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 UnauthenticatedError} When the client cannot authenticate with its credentials.
+     * @throws {@link UnknownDeviceError} When the device id does not match any device on the account.
+     * @throws {@link UnsupportedFanSpeedError} When the requested fan speed is not supported by the device.
      * @throws {@link Error} When MQTT connection or command sending fails.
      */
     setDeviceState(deviceId: string, setPoint?: number, mode?: MysaDeviceMode, fanSpeed?: MysaFanSpeedMode): Promise<void>;
@@ -974,16 +1033,49 @@ declare class MysaApiClient {
      * @throws {@link Error} When MQTT unsubscription fails.
      */
     stopRealtimeUpdates(deviceId: string): Promise<void>;
+    /**
+     * Subscribes to raw MQTT topic filters and relays every message verbatim.
+     *
+     * Unlike {@link startRealtimeUpdates}, this performs no parsing, emits no typed events and sends no "start publishing"
+     * request to the device — it simply forwards the full message topic and the decoded UTF-8 payload of everything that
+     * arrives on the given filters. It exists to reverse-engineer device families the SDK does not model yet, most
+     * notably the AWS IoT Device Shadow protocol used by the central-HVAC ST-V1 thermostats, where both the topic (which
+     * shadow, and `accepted`/`rejected`/`delta`/`documents`) and the raw JSON body carry the information a new
+     * implementation needs.
+     *
+     * The capture is passive: the device only publishes to its shadow topics when something drives a change (the Mysa
+     * mobile app, a schedule, or the device itself), so exercise the thermostat while a capture is running.
+     *
+     * Registered filters are re-subscribed automatically after a reconnect.
+     *
+     * @param topicFilters - MQTT topic filters to subscribe to. Wildcards (`+`, `#`) are allowed, subject to the AWS IoT
+     *   policy attached to the account's Cognito identity — a filter the policy forbids resolves with a non-zero
+     *   `error_code`, which is logged rather than thrown so the remaining filters still subscribe.
+     * @param handler - Invoked with the full message topic and the decoded UTF-8 payload for every message received.
+     * @throws {@link Error} When the MQTT connection cannot be established.
+     */
+    startRawTopicCapture(topicFilters: string[], handler: (topic: string, payload: string) => void): Promise<void>;
     /**
      * Ensures a valid, non-expired session is available.
      *
      * This method checks if the current session is valid and not expired. If the session is expired, it automatically
-     * refreshes it using the refresh token.
+     * refreshes it using the refresh token. If there is no session yet, or if the refresh token has itself expired or
+     * been revoked, the client logs back in with its credentials.
+     *
+     * Concurrent callers share a single in-flight acquisition, so a burst of API calls never triggers more than one
+     * refresh or login.
      *
      * @returns A promise that resolves to a valid CognitoUserSession.
-     * @throws {@link UnauthenticatedError} When no session exists or refresh fails.
+     * @throws {@link UnauthenticatedError} When neither refreshing nor logging back in succeeds.
      */
     private _getFreshSession;
+    /**
+     * Refreshes the current session, falling back to a full login when it cannot be refreshed.
+     *
+     * @returns A promise that resolves to a valid CognitoUserSession.
+     * @throws {@link UnauthenticatedError} When logging back in fails.
+     */
+    private _acquireFreshSession;
     /**
      * Establishes and returns an MQTT connection for real-time communication.
      *
@@ -1036,6 +1128,36 @@ declare class MysaApiClient {
      * @throws {@link Error} When connection establishment fails.
      */
     private _createMqttConnection;
+    /**
+     * Re-subscribes every device currently receiving real-time updates on the given connection.
+     *
+     * Safe to call on every (re)connect: aws-crt replaces the per-topic callback on a duplicate subscribe, so this never
+     * registers a message handler more than once.
+     *
+     * @param connection - The connection to (re-)establish subscriptions on.
+     */
+    private _resubscribeAll;
+    /**
+     * Arms (or re-arms) the stability timer. When a connection stays interrupt-free for {@link MqttStabilityWindow}, the
+     * consecutive-reset backoff counter is cleared so a future isolated storm still gets a fast first reset.
+     *
+     * @param generation - The connection generation that armed the timer; the callback is a no-op if the connection has
+     *   since been replaced.
+     */
+    private _armMqttStabilityTimer;
+    /** Clears the stability timer, if armed. */
+    private _clearMqttStabilityTimer;
+    /**
+     * Forcefully tears down the current MQTT connection and rebuilds it with a fresh client id and fresh credentials,
+     * escaping interrupt storms that a plain native reconnect cannot.
+     *
+     * Repeatable and self-contained: only one reset runs at a time, consecutive resets without an intervening stable
+     * period back off exponentially (up to {@link MqttResetMaxDelay}), and it never rejects — so it is safe to invoke
+     * fire-and-forget from an event handler.
+     *
+     * @param reason - Human-readable reason for the reset, used in logs.
+     */
+    private _resetMqttConnection;
     /**
      * Processes incoming MQTT messages and emits appropriate events.
      *
@@ -1158,4 +1280,4 @@ type MsgTypeInPayload = CheckDeviceSettings | StartPublishingDeviceStatus;
  */
 type InPayload = MsgTypeInPayload | MsgInPayload;
 
-export { type BrandInfo, type ChangeDeviceState, type CheckDeviceSettings, type DeviceAcStatus, 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, type HomeBase, type Homes, 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 };
+export { type BrandInfo, type ChangeDeviceState, type CheckDeviceSettings, type DeviceAcStatus, 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, type HomeBase, type Homes, 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 MysaCredentials, type MysaDeviceMode, type MysaFanSpeedMode, OutMessageType, type OutPayload, type SetPointChange, type StartPublishingDeviceStatus, type StateChange, type Status, type SupportedCaps, type TimestampedValue, UnauthenticatedError, UnknownDeviceError, UnsupportedFanSpeedError, VoidLogger };