mysa-js-sdk 2.1.1 → 3.0.0

package/dist/index.js

@@ -24,14 +24,24 @@ SOFTWARE.
 
 // src/api/Errors.ts
 var UnauthenticatedError = class 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.
+   */
+  cause;
   /**
    * Creates a new UnauthenticatedError instance.
    *
    * @param message - The error message
+   * @param cause - The underlying failure that prevented authentication, if any.
    */
-  constructor(message) {
+  constructor(message, cause) {
     super(message);
     this.name = "UnauthenticatedError";
+    this.cause = cause;
   }
 };
 var MysaApiError = class extends Error {
@@ -53,6 +63,19 @@ var MysaApiError = class extends Error {
     this.statusText = apiResponse.statusText;
   }
 };
+var UnknownDeviceError = class extends Error {
+  /**
+   * Creates a new UnknownDeviceError instance.
+   *
+   * @param deviceId - The device id that could not be resolved
+   */
+  constructor(deviceId) {
+    super(`Unknown device id '${deviceId}': no such device on this account.`);
+    this.deviceId = deviceId;
+    this.name = "UnknownDeviceError";
+  }
+  deviceId;
+};
 var MqttPublishError = class extends Error {
   /**
    * Creates a new MqttPublishError instance.
@@ -150,8 +173,9 @@ function parseMqttPayload(payload) {
     const jsonString = decoder.decode(payload);
     return JSON.parse(jsonString);
   } catch (error) {
-    console.error("Error parsing MQTT payload:", error);
-    throw new Error("Failed to parse MQTT payload");
+    const parseError = new Error("Failed to parse MQTT payload");
+    parseError.cause = error;
+    throw parseError;
   }
 }
 function serializeMqttPayload(payload) {
@@ -191,15 +215,7 @@ var OutMessageType = /* @__PURE__ */ ((OutMessageType2) => {
 // src/api/MysaApiClient.ts
 import { DescribeThingCommand, IoTClient } from "@aws-sdk/client-iot";
 import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers";
-import {
-  AuthenticationDetails,
-  CognitoAccessToken,
-  CognitoIdToken,
-  CognitoRefreshToken,
-  CognitoUser,
-  CognitoUserPool,
-  CognitoUserSession
-} from "amazon-cognito-identity-js";
+import { AuthenticationDetails, CognitoUser, CognitoUserPool } from "amazon-cognito-identity-js";
 import { auth, iot, mqtt } from "aws-iot-device-sdk-v2";
 import { hash } from "crypto";
 import dayjs from "dayjs";
@@ -215,11 +231,16 @@ var CognitoLoginKey = `cognito-idp.${AwsRegion}.amazonaws.com/${CognitoUserPoolI
 var MqttEndpoint = "a3q27gia9qg3zy-ats.iot.us-east-1.amazonaws.com";
 var MysaApiBaseUrl = "https://app-prod.mysa.cloud";
 var RealtimeKeepAliveInterval = dayjs.duration(5, "minutes");
+var PublishAckTimeout = dayjs.duration(30, "seconds");
 var MysaApiClient = class {
+  /** The credentials of the Mysa account this client authenticates as. */
+  _credentials;
   /** The current session object, if any. */
   _cognitoUserSession;
   /** The current user object, if any. */
   _cognitoUser;
+  /** The in-flight session acquisition, if any, so that concurrent callers share a single refresh or login. */
+  _freshSessionPromise;
   /** The logger instance used by the client. */
   _logger;
   /** The fetcher function used by the client. */
@@ -244,89 +265,62 @@ var MysaApiClient = class {
    * @see {@link MysaApiClientEventTypes} for the possible events and their payloads.
    */
   emitter = new EventEmitter();
-  /**
-   * Gets the persistable session object.
-   *
-   * @returns The current persistable session object, if any.
-   */
-  get session() {
-    if (!this._cognitoUserSession || !this._cognitoUser) {
-      return void 0;
-    }
-    return {
-      username: this._cognitoUser.getUsername(),
-      idToken: this._cognitoUserSession.getIdToken().getJwtToken(),
-      accessToken: this._cognitoUserSession.getAccessToken().getJwtToken(),
-      refreshToken: this._cognitoUserSession.getRefreshToken().getToken()
-    };
-  }
-  /**
-   * Returns whether the client currently has an active session.
-   *
-   * @returns True if the client has an active session, false otherwise.
-   */
-  get isAuthenticated() {
-    return !!this.session;
-  }
   /**
    * 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, options) {
+  constructor(credentials, options) {
+    this._credentials = credentials;
     this._logger = (options == null ? void 0 : options.logger) || new VoidLogger();
     this._fetcher = (options == null ? void 0 : options.fetcher) || fetch;
-    if (session) {
-      this._cognitoUser = new CognitoUser({
-        Username: session.username,
-        Pool: new CognitoUserPool({ UserPoolId: CognitoUserPoolId, ClientId: CognitoClientId })
-      });
-      this._cognitoUserSession = new CognitoUserSession({
-        IdToken: new CognitoIdToken({ IdToken: session.idToken }),
-        AccessToken: new CognitoAccessToken({ AccessToken: session.accessToken }),
-        RefreshToken: new CognitoRefreshToken({ RefreshToken: session.refreshToken })
-      });
-    }
   }
   /**
-   * 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.
+   */
+  async login() {
+    await this._getFreshSession();
+  }
+  /**
+   * 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.
    */
-  async login(emailAddress, password) {
+  _login() {
     this._cognitoUser = void 0;
     this._cognitoUserSession = void 0;
     this._mqttClientId = void 0;
     this._mqttInterrupts = [];
-    this.emitter.emit("sessionChanged", this.session);
+    const { username, password } = this._credentials;
     return new Promise((resolve, reject) => {
       const user = new CognitoUser({
-        Username: emailAddress,
+        Username: username,
         Pool: new CognitoUserPool({ UserPoolId: CognitoUserPoolId, ClientId: CognitoClientId })
       });
-      user.authenticateUser(new AuthenticationDetails({ Username: emailAddress, Password: password }), {
+      user.authenticateUser(new AuthenticationDetails({ Username: username, Password: password }), {
         onSuccess: (session) => {
           this._cognitoUser = user;
           this._cognitoUserSession = session;
-          this.emitter.emit("sessionChanged", this.session);
-          resolve();
+          resolve(session);
         },
         onFailure: (err) => {
           reject(err);
@@ -351,7 +345,7 @@ var MysaApiClient = class {
    *
    * @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.
    */
   async getDevices() {
     this._logger.debug(`Fetching devices...`);
@@ -385,7 +379,7 @@ var MysaApiClient = class {
    *
    * @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.
    */
   async getDeviceSerialNumber(deviceId) {
     var _a;
@@ -423,7 +417,7 @@ var MysaApiClient = class {
    *
    * @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.
    */
   async getDeviceFirmwares() {
     this._logger.debug(`Fetching device firmwares...`);
@@ -443,7 +437,7 @@ var MysaApiClient = class {
    *
    * @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.
    */
   async getDeviceStates() {
     this._logger.debug(`Fetching device states...`);
@@ -463,7 +457,7 @@ var MysaApiClient = class {
    *
    * @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.
    */
   async getHomes() {
     this._logger.debug(`Fetching homes...`);
@@ -505,16 +499,20 @@ var MysaApiClient = class {
    * @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 Error} When MQTT connection or command sending fails.
    */
   async setDeviceState(deviceId, setPoint, mode, fanSpeed) {
-    var _a;
     this._logger.debug(`Setting device state for '${deviceId}'`);
     if (!this._cachedDevices) {
       this._cachedDevices = await this.getDevices();
     }
+    if (!Object.prototype.hasOwnProperty.call(this._cachedDevices.DevicesObj, deviceId)) {
+      throw new UnknownDeviceError(deviceId);
+    }
     const device = this._cachedDevices.DevicesObj[deviceId];
+    await this._getFreshSession();
     this._logger.debug(`Initializing MQTT connection...`);
     const mqttConnection = await this._getMqttConnection();
     const now = dayjs();
@@ -527,7 +525,7 @@ var MysaApiClient = class {
       time: now.unix(),
       ver: "1.0",
       src: {
-        ref: ((_a = this.session) == null ? void 0 : _a.username) ?? "",
+        ref: this._cognitoUser.getUsername(),
         type: 100
       },
       dest: {
@@ -596,17 +594,25 @@ var MysaApiClient = class {
       Timestamp: dayjs().unix(),
       Timeout: RealtimeKeepAliveInterval.asSeconds()
     });
-    await this._publishWithRetry(mqttConnection, `/v1/dev/${deviceId}/in`, payload, mqtt.QoS.AtLeastOnce);
+    try {
+      await this._publishWithRetry(mqttConnection, `/v1/dev/${deviceId}/in`, payload, mqtt.QoS.AtLeastOnce);
+    } catch (error) {
+      this._logger.warn(`Failed to request status publishing for '${deviceId}'; relying on periodic reports`, error);
+    }
     const timer = setInterval(async () => {
       this._logger.debug(`Sending request to keep-alive publishing device status for '${deviceId}'...`);
-      const connection = await this._getMqttConnection();
-      const payload2 = serializeMqttPayload({
-        Device: deviceId,
-        MsgType: 11 /* START_PUBLISHING_DEVICE_STATUS */,
-        Timestamp: dayjs().unix(),
-        Timeout: RealtimeKeepAliveInterval.asSeconds()
-      });
-      await this._publishWithRetry(connection, `/v1/dev/${deviceId}/in`, payload2, mqtt.QoS.AtLeastOnce);
+      try {
+        const connection = await this._getMqttConnection();
+        const payload2 = serializeMqttPayload({
+          Device: deviceId,
+          MsgType: 11 /* START_PUBLISHING_DEVICE_STATUS */,
+          Timestamp: dayjs().unix(),
+          Timeout: RealtimeKeepAliveInterval.asSeconds()
+        });
+        await this._publishWithRetry(connection, `/v1/dev/${deviceId}/in`, payload2, mqtt.QoS.AtLeastOnce);
+      } catch (error) {
+        this._logger.warn(`Failed to keep-alive status publishing for '${deviceId}'`, error);
+      }
     }, RealtimeKeepAliveInterval.subtract(10, "seconds").asMilliseconds());
     this._realtimeDeviceIds.set(deviceId, timer);
   }
@@ -637,33 +643,58 @@ var MysaApiClient = class {
    * 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.
    */
   async _getFreshSession() {
-    if (!this._cognitoUser || !this._cognitoUserSession) {
-      throw new UnauthenticatedError("An attempt was made to access a resource without a valid session.");
-    }
-    if (this._cognitoUserSession.isValid() && dayjs.unix(this._cognitoUserSession.getIdToken().getExpiration()).isAfter()) {
+    var _a;
+    if (this._cognitoUser && ((_a = this._cognitoUserSession) == null ? void 0 : _a.isValid()) && dayjs.unix(this._cognitoUserSession.getIdToken().getExpiration()).isAfter()) {
       this._logger.debug("Session is valid, no need to refresh");
-      return Promise.resolve(this._cognitoUserSession);
+      return this._cognitoUserSession;
     }
-    this._logger.debug("Session is not valid or expired, refreshing...");
-    return new Promise((resolve, reject) => {
-      this._cognitoUser.refreshSession(this._cognitoUserSession.getRefreshToken(), (error, session) => {
-        if (error) {
-          this._logger.error("Failed to refresh session:", error);
-          reject(new UnauthenticatedError("Unable to refresh the authentication session."));
-        } else {
-          this._logger.debug("Session refreshed successfully");
-          this._cognitoUserSession = session;
-          this.emitter.emit("sessionChanged", this.session);
-          resolve(session);
-        }
-      });
+    this._freshSessionPromise ??= this._acquireFreshSession().finally(() => {
+      this._freshSessionPromise = void 0;
     });
+    return this._freshSessionPromise;
+  }
+  /**
+   * 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.
+   */
+  async _acquireFreshSession() {
+    if (this._cognitoUser && this._cognitoUserSession) {
+      this._logger.debug("Session is not valid or expired, refreshing...");
+      try {
+        return await new Promise((resolve, reject) => {
+          this._cognitoUser.refreshSession(this._cognitoUserSession.getRefreshToken(), (error, session) => {
+            if (error) {
+              reject(error);
+            } else {
+              this._logger.debug("Session refreshed successfully");
+              this._cognitoUserSession = session;
+              resolve(session);
+            }
+          });
+        });
+      } catch (error) {
+        this._logger.warn("Failed to refresh session, logging back in:", error);
+      }
+    }
+    try {
+      this._logger.info("Logging in...");
+      return await this._login();
+    } catch (error) {
+      this._logger.error("Failed to log in:", error);
+      throw new UnauthenticatedError("Unable to establish an authentication session.", error);
+    }
   }
   /**
    * Establishes and returns an MQTT connection for real-time communication.
@@ -741,7 +772,22 @@ var MysaApiClient = class {
     while (true) {
       attempt++;
       try {
-        await connection.publish(topic, payload, qos);
+        await new Promise((resolve, reject) => {
+          const timer = setTimeout(
+            () => reject(new Error(`MQTT publish timeout: no acknowledgement within ${PublishAckTimeout.asSeconds()}s`)),
+            PublishAckTimeout.asMilliseconds()
+          );
+          connection.publish(topic, payload, qos).then(
+            () => {
+              clearTimeout(timer);
+              resolve();
+            },
+            (err) => {
+              clearTimeout(timer);
+              reject(err);
+            }
+          );
+        });
         return;
       } catch (err) {
         const isTransient = this._isTransientMqttError(err);
@@ -790,7 +836,7 @@ var MysaApiClient = class {
       throw new Error("MQTT credentials are already expired.");
     }
     if (!this._mqttClientId) {
-      const username = ((_a = this.session) == null ? void 0 : _a.username) ?? "anon";
+      const username = ((_a = this._cognitoUser) == null ? void 0 : _a.getUsername()) ?? "anon";
       const usernameHash = hash("sha1", username);
       this._mqttClientId = `mysa-js-sdk-${usernameHash}-${process.pid}-${getRandomClientId()}`;
     }
@@ -1002,6 +1048,7 @@ export {
   MysaApiError,
   OutMessageType,
   UnauthenticatedError,
+  UnknownDeviceError,
   VoidLogger
 };
 //# sourceMappingURL=index.js.map