mysa-js-sdk 2.1.2 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # mysa-js-sdk
 
+## 3.0.0
+
+### Major Changes
+
+- [#199](https://github.com/bourquep/mysa2mqtt/pull/199) [`b384d79`](https://github.com/bourquep/mysa2mqtt/commit/b384d7950d757bc85af7580eaa26435190b47364) Thanks [@bourquep](https://github.com/bourquep)! - The client now takes Mysa account credentials instead of a session object, and re-authenticates on its own when its refresh token expires or is revoked, so long-running processes no longer die after about a month. `new MysaApiClient(session, options)` becomes `new MysaApiClient({ username, password }, options)`, `login()` no longer takes arguments and is optional (the client authenticates on demand), and the `MysaSession` type, the `session` and `isAuthenticated` properties, and the `sessionChanged` event are gone — there is no longer any session state to persist.
+
+### Patch Changes
+
+- [#201](https://github.com/bourquep/mysa2mqtt/pull/201) [`10ee91c`](https://github.com/bourquep/mysa2mqtt/commit/10ee91c1981b77ef1e9f76abd3d24ba6d9a19d77) Thanks [@bourquep](https://github.com/bourquep)! - A Mysa login rejected for a bad password now reports that a `$` in it is expanded by shells and by Docker Compose (in both `environment:` entries and default-format `env_file:` files, where it must be written `$$`, but not in an `env_file:` declared with `format: raw`), and that an unquoted `#` truncates a `.env` value, instead of surfacing a bare `Incorrect username or password.` stack trace. An unrecognized account gets username-specific guidance instead, since none of the password escaping rules apply to it. Transport and Cognito service failures keep propagating without that guidance, since `UnauthenticatedError` now carries the underlying failure as its `cause`. Debug logging also reports the length of the password that was actually received -- never the password or the account it belongs to -- so a mangled value can be spotted at a glance.
+
+- [#190](https://github.com/bourquep/mysa2mqtt/pull/190) [`7169263`](https://github.com/bourquep/mysa2mqtt/commit/7169263fcb4b2aeb51c7eae4c112972c3e2fdb08) Thanks [@vavallee](https://github.com/vavallee)! - Payload parse failures no longer write to console.error, which bypassed the configurable SDK logger and could leak payload contents. The error is rethrown with the original failure attached as cause and logged by the message handler through the SDK logger.
+
+- [#191](https://github.com/bourquep/mysa2mqtt/pull/191) [`527ef25`](https://github.com/bourquep/mysa2mqtt/commit/527ef25886aad766a2fd71fc92002d8de126b364) Thanks [@vavallee](https://github.com/vavallee)! - setDeviceState now throws a descriptive UnknownDeviceError when the device id does not match any device on the account, instead of failing with a raw TypeError on an undefined dereference.
+
+- [#200](https://github.com/bourquep/mysa2mqtt/pull/200) [`61dc2a2`](https://github.com/bourquep/mysa2mqtt/commit/61dc2a2b395397e9e5245098bfd31b49b501fd7d) Thanks [@bourquep](https://github.com/bourquep)! - V2 thermostats can now report power. These devices have no current sensor and only report the duty cycle of their heating relay, which is why their **Current power** sensor has always been unavailable. Set the new `--heater-watts` option (`M2M_HEATER_WATTS`) to the rated wattage of the heaters each thermostat controls — for example `M2M_HEATER_WATTS="Kitchen=1500,<device-id>=750"`, matching devices by name or id — and power is estimated as `duty cycle × rated wattage`. V1 thermostats measure their own current and continue to work with no configuration.
+
+  The power sensor is now only created for devices that can actually report a value. If you have AC devices, or V2 thermostats for which you have not configured a wattage, their **Current power** entity is removed from Home Assistant on startup; it only ever showed as unavailable.
+
+  `mqtt2ha` gains a `Discoverable.removeConfig()` method, which clears an entity's retained discovery topic so Home Assistant drops the entity. This is what makes the removal above take effect: because `writeConfig()` retains its payload, an entity published by an earlier run persists until its topic is explicitly cleared.
+
 ## 2.1.2
 
 ### Patch Changes

package/README.md

@@ -66,17 +66,20 @@ The Mysa SDK provides a simple interface to interact with Mysa smart thermostats
 ```typescript
 import { MysaApiClient } from 'mysa-js-sdk';
 
-const client = new MysaApiClient();
-
-// Login with email and password
-await client.login('your-email@example.com', 'your-password');
+// The client holds your credentials and authenticates on demand
+const client = new MysaApiClient({
+  username: 'your-email@example.com',
+  password: 'your-password'
+});
 
-// Check if authenticated
-if (client.isAuthenticated) {
-  console.log('Successfully authenticated!');
-}
+// Optional: log in eagerly to fail fast on invalid credentials
+await client.login();
 ```
 
+The client manages its session on its own: it refreshes the session when it needs to, and logs back in automatically
+when the refresh token has itself expired or been revoked. There is nothing to persist, and no need to re-create the
+client after a long run.
+
 ### Retrieving Thermostat Data
 
 Once authenticated, you can access your thermostat data:
@@ -139,10 +142,9 @@ The SDK provides specific error types to handle API errors:
 ```typescript
 import { MysaApiClient, MysaApiError, UnauthenticatedError } from 'mysa-js-sdk';
 
-const client = new MysaApiClient();
+const client = new MysaApiClient({ username: 'user@example.com', password: 'password' });
 
 try {
-  await client.login('user@example.com', 'password');
   const devices = await client.getDevices();
 } catch (error) {
   if (error instanceof UnauthenticatedError) {
@@ -170,31 +172,13 @@ const logger = pino({
 });
 
 // Configure client with options
-const client = new MysaApiClient(undefined, {
-  logger: logger,
-  fetcher: fetch // Custom fetch implementation if needed
-});
-
-// Or restore from a saved session
-const savedSession = {
-  username: 'user@example.com',
-  idToken: 'eyJ...',
-  accessToken: 'eyJ...',
-  refreshToken: 'abc123...'
-};
-
-const clientWithSession = new MysaApiClient(savedSession, { logger });
-
-// Listen for session changes to persist them
-client.emitter.on('sessionChanged', (newSession) => {
-  if (newSession) {
-    // Save session to storage (file, database, etc.)
-    localStorage.setItem('mysaSession', JSON.stringify(newSession));
-  } else {
-    // Session expired or logged out
-    localStorage.removeItem('mysaSession');
+const client = new MysaApiClient(
+  { username: 'user@example.com', password: 'password' },
+  {
+    logger: logger,
+    fetcher: fetch // Custom fetch implementation if needed
   }
-});
+);
 ```
 
 ### Reference documentation

package/dist/index.cjs

@@ -59,20 +59,31 @@ __export(index_exports, {
   MysaApiError: () => MysaApiError,
   OutMessageType: () => OutMessageType,
   UnauthenticatedError: () => UnauthenticatedError,
+  UnknownDeviceError: () => UnknownDeviceError,
   VoidLogger: () => VoidLogger
 });
 module.exports = __toCommonJS(index_exports);
 
 // 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 {
@@ -94,6 +105,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.
@@ -191,8 +215,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) {
@@ -250,10 +275,14 @@ var MysaApiBaseUrl = "https://app-prod.mysa.cloud";
 var RealtimeKeepAliveInterval = import_dayjs.default.duration(5, "minutes");
 var PublishAckTimeout = import_dayjs.default.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. */
@@ -278,89 +307,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 import_amazon_cognito_identity_js.CognitoUser({
-        Username: session.username,
-        Pool: new import_amazon_cognito_identity_js.CognitoUserPool({ UserPoolId: CognitoUserPoolId, ClientId: CognitoClientId })
-      });
-      this._cognitoUserSession = new import_amazon_cognito_identity_js.CognitoUserSession({
-        IdToken: new import_amazon_cognito_identity_js.CognitoIdToken({ IdToken: session.idToken }),
-        AccessToken: new import_amazon_cognito_identity_js.CognitoAccessToken({ AccessToken: session.accessToken }),
-        RefreshToken: new import_amazon_cognito_identity_js.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 import_amazon_cognito_identity_js.CognitoUser({
-        Username: emailAddress,
+        Username: username,
         Pool: new import_amazon_cognito_identity_js.CognitoUserPool({ UserPoolId: CognitoUserPoolId, ClientId: CognitoClientId })
       });
-      user.authenticateUser(new import_amazon_cognito_identity_js.AuthenticationDetails({ Username: emailAddress, Password: password }), {
+      user.authenticateUser(new import_amazon_cognito_identity_js.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);
@@ -385,7 +387,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...`);
@@ -419,7 +421,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;
@@ -457,7 +459,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...`);
@@ -477,7 +479,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...`);
@@ -497,7 +499,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...`);
@@ -539,16 +541,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 = (0, import_dayjs.default)();
@@ -561,7 +567,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: {
@@ -679,33 +685,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() && import_dayjs.default.unix(this._cognitoUserSession.getIdToken().getExpiration()).isAfter()) {
+    var _a;
+    if (this._cognitoUser && ((_a = this._cognitoUserSession) == null ? void 0 : _a.isValid()) && import_dayjs.default.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.
@@ -847,7 +878,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 = (0, import_crypto.hash)("sha1", username);
       this._mqttClientId = `mysa-js-sdk-${usernameHash}-${process.pid}-${getRandomClientId()}`;
     }
@@ -1060,6 +1091,7 @@ var MysaApiClient = class {
   MysaApiError,
   OutMessageType,
   UnauthenticatedError,
+  UnknownDeviceError,
   VoidLogger
 });
 //# sourceMappingURL=index.cjs.map