@apocaliss92/nodedreame 1.11.9 → 1.11.11

package/dist/index.d.cts

@@ -169,6 +169,8 @@ declare class TypedEmitter<Events extends Record<string, unknown[]>> {
     once<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
     off<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
     emit<K extends keyof Events & string>(event: K, ...args: Events[K]): boolean;
+    /** Number of listeners registered for `event`. */
+    listenerCount<K extends keyof Events & string>(event: K): number;
     removeAllListeners(): this;
 }
 
@@ -179,6 +181,14 @@ interface PropertyChange {
     piid: number;
     value: unknown;
 }
+/**
+ * True when `err` (or an error in its `cause` chain) is an MQTT CONNACK
+ * auth-refusal. mqtt.js raises an `ErrorWithReasonCode` carrying a numeric
+ * `code`: MQTT 3.1.1 uses 4 (bad user/pass) / 5 (not authorized); MQTT 5 uses
+ * 134 / 135. We also match the human-readable message as a belt-and-braces
+ * fallback in case the code is not surfaced through a wrapper.
+ */
+declare function isAuthRefusedError(err: unknown): boolean;
 
 /**
  * A read-only set of capability tokens a device model supports. Phase 2 ships
@@ -294,7 +304,7 @@ interface PushLike {
 }
 /** Injectable collaborators — defaults wire the real transport + command layer. */
 interface BaseDeviceDeps {
-    createPush(device: DreameDevice, session: DreameSession, region: DreameRegion): PushLike;
+    createPush(device: DreameDevice, session: DreameSession, region: DreameRegion, onAuthFailure?: () => Promise<DreameSession>): PushLike;
     getProperties(base: CommonInput, props: MiotProp[]): Promise<PropertyResult[]>;
     /** Read the cloud-cached (shadow) values WITHOUT waking the device. */
     getCachedProperties(base: CommonInput, props: MiotProp[]): Promise<PropertyResult[]>;
@@ -316,6 +326,12 @@ interface BaseDeviceInput {
     region: DreameRegion;
     /** Always reads the LATEST session — the facade owns the variable. */
     sessionRef: () => DreameSession;
+    /**
+     * Force-refresh callback handed to the underlying push so it can self-heal a
+     * broker CONNACK auth-refusal (stale token) by minting a fresh session.
+     * Wired by the facade to `Nodreame.reauthenticate()`.
+     */
+    onAuthFailure?: () => Promise<DreameSession>;
     deps?: BaseDeviceDeps;
     /** Eager-seed the cache on `start()`. Default true. */
     fetchInitialValues?: boolean;
@@ -376,6 +392,12 @@ interface CreateDeviceArgs {
     device: DreameDevice;
     region: DreameRegion;
     sessionRef: () => DreameSession;
+    /**
+     * Force-refresh callback handed down to the device's MQTT push so it can
+     * self-heal a broker CONNACK auth-refusal (stale token). Bound by the facade
+     * to {@link Nodreame.reauthenticate}.
+     */
+    onAuthFailure?: () => Promise<DreameSession>;
 }
 /** Injectable collaborators — defaults wire the real P1 modules. */
 interface NodreameDeps {
@@ -419,6 +441,15 @@ declare class Nodreame extends TypedEmitter<NodreameEvents> {
     login(): Promise<DreameSession>;
     /** Return a valid session, refreshing proactively within the leeway window. */
     ensureSession(): Promise<DreameSession>;
+    /**
+     * Force a session refresh REGARDLESS of the current expiry, then propagate the
+     * new token to every live device push. Wired as each push's `onAuthFailure`:
+     * when a broker refuses a CONNECT because it considers the token stale (even
+     * though {@link ensureSession} still thinks it valid — e.g. server-side early
+     * revocation or clock skew), this mints a genuinely fresh token instead of
+     * replaying the rejected one.
+     */
+    reauthenticate(): Promise<DreameSession>;
     /** Discover devices and build a live handle per device. */
     discoverDevices(): Promise<readonly BaseDevice[]>;
     /** Tear everything down: close every device push and clear timers. */
@@ -2598,4 +2629,4 @@ declare function createDumper(target: DumperDevice, options?: DumperOptions): Du
  */
 declare function createClientDumper(client: Nodreame, options?: DumperOptions): Dumper[];
 
-export { AI_FEATURE_BIT, AI_FEATURE_JSON_KEY, AUTO_SWITCH_JSON_KEY, type AiDetectionRaw, type AutoSwitchKey, type AutoSwitchRaw, BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type ConsumableReading, type ConsumableSpec, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceDump, type DeviceEvent, type DreameAiFeature, DreameApiError, DreameAuthError, type DreameCloudState, type DreameConsumableKey, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, type DumperOptions, LIBRARY_NAME, MODEL_CAPABILITIES as MOWER_MODEL_CAPABILITIES, MOWER_TASK_SUBSTATES, type MapBoundingBox, type MapCleanedAreaOverlay, type MapColorScheme, type MapDimensions, type MapFrameType, type MapLayer, type MapLayerType, type MapLowLyingArea, type MapObstacle, type MapPath, type MapPathType, type MapPoint, type MapPose, type MapRestrictedArea, type MapRoom, type MapRoomWall, type MapRun, type MapSegment, type MapStorey, type MapVirtualWall, type MapWallsInfo, type MiotAction, MiotError, type MiotProp, MiotState, type MowerAvailableMap, type MowerCapabilities, MowerCapabilityResolver, MowerChargingStatus, type MowerConsumableKey, type MowerConsumableReading, type MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerFaultSeverity, type MowerHeartbeat, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerMowingProgress, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, type MowerTaskSubState, type MowerZone, Nodreame, type NodreameDeps, type NodreameEvents, type NodreameOptions, type OssFetchInput, type OssFetcherLike, type PropertyChangedEvent, type PropertyResult, type PropertyState, type PropertyWrite, type RenderMowerSvgOptions, type RenderVacuumPngOptions, type StateChangedEvent, SuctionLevel, TaskStatus, VACUUM_CONSUMABLES, MODEL_CAPABILITIES$1 as VACUUM_MODEL_CAPABILITIES, type VacuumCapabilities, VacuumCapabilityResolver, VacuumDevice, type VacuumGetMapInput, type VacuumMap, WaterVolume, consumableSpec, createClientDumper, createDumper, decodeAiFeature, decodeAutoSwitch, decodeAutoSwitchAll, encodeAiFeatureWrite, encodeAutoSwitchWrite, extractMowerConsumableValues, getMowerCapabilities, getVacuumCapabilities, isDreameConsumableKey, mowerConsumableIndex, mowerFaultSeverity, parseMowerConsumables, parseMowerHeartbeat, parseMowingProgress, renderMowerSvg, renderVacuumPng, resolveCapabilities, supportedAutoSwitchKeys };
+export { AI_FEATURE_BIT, AI_FEATURE_JSON_KEY, AUTO_SWITCH_JSON_KEY, type AiDetectionRaw, type AutoSwitchKey, type AutoSwitchRaw, BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type ConsumableReading, type ConsumableSpec, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceDump, type DeviceEvent, type DreameAiFeature, DreameApiError, DreameAuthError, type DreameCloudState, type DreameConsumableKey, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, type DumperOptions, LIBRARY_NAME, MODEL_CAPABILITIES as MOWER_MODEL_CAPABILITIES, MOWER_TASK_SUBSTATES, type MapBoundingBox, type MapCleanedAreaOverlay, type MapColorScheme, type MapDimensions, type MapFrameType, type MapLayer, type MapLayerType, type MapLowLyingArea, type MapObstacle, type MapPath, type MapPathType, type MapPoint, type MapPose, type MapRestrictedArea, type MapRoom, type MapRoomWall, type MapRun, type MapSegment, type MapStorey, type MapVirtualWall, type MapWallsInfo, type MiotAction, MiotError, type MiotProp, MiotState, type MowerAvailableMap, type MowerCapabilities, MowerCapabilityResolver, MowerChargingStatus, type MowerConsumableKey, type MowerConsumableReading, type MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerFaultSeverity, type MowerHeartbeat, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerMowingProgress, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, type MowerTaskSubState, type MowerZone, Nodreame, type NodreameDeps, type NodreameEvents, type NodreameOptions, type OssFetchInput, type OssFetcherLike, type PropertyChangedEvent, type PropertyResult, type PropertyState, type PropertyWrite, type RenderMowerSvgOptions, type RenderVacuumPngOptions, type StateChangedEvent, SuctionLevel, TaskStatus, VACUUM_CONSUMABLES, MODEL_CAPABILITIES$1 as VACUUM_MODEL_CAPABILITIES, type VacuumCapabilities, VacuumCapabilityResolver, VacuumDevice, type VacuumGetMapInput, type VacuumMap, WaterVolume, consumableSpec, createClientDumper, createDumper, decodeAiFeature, decodeAutoSwitch, decodeAutoSwitchAll, encodeAiFeatureWrite, encodeAutoSwitchWrite, extractMowerConsumableValues, getMowerCapabilities, getVacuumCapabilities, isAuthRefusedError, isDreameConsumableKey, mowerConsumableIndex, mowerFaultSeverity, parseMowerConsumables, parseMowerHeartbeat, parseMowingProgress, renderMowerSvg, renderVacuumPng, resolveCapabilities, supportedAutoSwitchKeys };

package/dist/index.d.ts

@@ -169,6 +169,8 @@ declare class TypedEmitter<Events extends Record<string, unknown[]>> {
     once<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
     off<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => void): this;
     emit<K extends keyof Events & string>(event: K, ...args: Events[K]): boolean;
+    /** Number of listeners registered for `event`. */
+    listenerCount<K extends keyof Events & string>(event: K): number;
     removeAllListeners(): this;
 }
 
@@ -179,6 +181,14 @@ interface PropertyChange {
     piid: number;
     value: unknown;
 }
+/**
+ * True when `err` (or an error in its `cause` chain) is an MQTT CONNACK
+ * auth-refusal. mqtt.js raises an `ErrorWithReasonCode` carrying a numeric
+ * `code`: MQTT 3.1.1 uses 4 (bad user/pass) / 5 (not authorized); MQTT 5 uses
+ * 134 / 135. We also match the human-readable message as a belt-and-braces
+ * fallback in case the code is not surfaced through a wrapper.
+ */
+declare function isAuthRefusedError(err: unknown): boolean;
 
 /**
  * A read-only set of capability tokens a device model supports. Phase 2 ships
@@ -294,7 +304,7 @@ interface PushLike {
 }
 /** Injectable collaborators — defaults wire the real transport + command layer. */
 interface BaseDeviceDeps {
-    createPush(device: DreameDevice, session: DreameSession, region: DreameRegion): PushLike;
+    createPush(device: DreameDevice, session: DreameSession, region: DreameRegion, onAuthFailure?: () => Promise<DreameSession>): PushLike;
     getProperties(base: CommonInput, props: MiotProp[]): Promise<PropertyResult[]>;
     /** Read the cloud-cached (shadow) values WITHOUT waking the device. */
     getCachedProperties(base: CommonInput, props: MiotProp[]): Promise<PropertyResult[]>;
@@ -316,6 +326,12 @@ interface BaseDeviceInput {
     region: DreameRegion;
     /** Always reads the LATEST session — the facade owns the variable. */
     sessionRef: () => DreameSession;
+    /**
+     * Force-refresh callback handed to the underlying push so it can self-heal a
+     * broker CONNACK auth-refusal (stale token) by minting a fresh session.
+     * Wired by the facade to `Nodreame.reauthenticate()`.
+     */
+    onAuthFailure?: () => Promise<DreameSession>;
     deps?: BaseDeviceDeps;
     /** Eager-seed the cache on `start()`. Default true. */
     fetchInitialValues?: boolean;
@@ -376,6 +392,12 @@ interface CreateDeviceArgs {
     device: DreameDevice;
     region: DreameRegion;
     sessionRef: () => DreameSession;
+    /**
+     * Force-refresh callback handed down to the device's MQTT push so it can
+     * self-heal a broker CONNACK auth-refusal (stale token). Bound by the facade
+     * to {@link Nodreame.reauthenticate}.
+     */
+    onAuthFailure?: () => Promise<DreameSession>;
 }
 /** Injectable collaborators — defaults wire the real P1 modules. */
 interface NodreameDeps {
@@ -419,6 +441,15 @@ declare class Nodreame extends TypedEmitter<NodreameEvents> {
     login(): Promise<DreameSession>;
     /** Return a valid session, refreshing proactively within the leeway window. */
     ensureSession(): Promise<DreameSession>;
+    /**
+     * Force a session refresh REGARDLESS of the current expiry, then propagate the
+     * new token to every live device push. Wired as each push's `onAuthFailure`:
+     * when a broker refuses a CONNECT because it considers the token stale (even
+     * though {@link ensureSession} still thinks it valid — e.g. server-side early
+     * revocation or clock skew), this mints a genuinely fresh token instead of
+     * replaying the rejected one.
+     */
+    reauthenticate(): Promise<DreameSession>;
     /** Discover devices and build a live handle per device. */
     discoverDevices(): Promise<readonly BaseDevice[]>;
     /** Tear everything down: close every device push and clear timers. */
@@ -2598,4 +2629,4 @@ declare function createDumper(target: DumperDevice, options?: DumperOptions): Du
  */
 declare function createClientDumper(client: Nodreame, options?: DumperOptions): Dumper[];
 
-export { AI_FEATURE_BIT, AI_FEATURE_JSON_KEY, AUTO_SWITCH_JSON_KEY, type AiDetectionRaw, type AutoSwitchKey, type AutoSwitchRaw, BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type ConsumableReading, type ConsumableSpec, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceDump, type DeviceEvent, type DreameAiFeature, DreameApiError, DreameAuthError, type DreameCloudState, type DreameConsumableKey, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, type DumperOptions, LIBRARY_NAME, MODEL_CAPABILITIES as MOWER_MODEL_CAPABILITIES, MOWER_TASK_SUBSTATES, type MapBoundingBox, type MapCleanedAreaOverlay, type MapColorScheme, type MapDimensions, type MapFrameType, type MapLayer, type MapLayerType, type MapLowLyingArea, type MapObstacle, type MapPath, type MapPathType, type MapPoint, type MapPose, type MapRestrictedArea, type MapRoom, type MapRoomWall, type MapRun, type MapSegment, type MapStorey, type MapVirtualWall, type MapWallsInfo, type MiotAction, MiotError, type MiotProp, MiotState, type MowerAvailableMap, type MowerCapabilities, MowerCapabilityResolver, MowerChargingStatus, type MowerConsumableKey, type MowerConsumableReading, type MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerFaultSeverity, type MowerHeartbeat, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerMowingProgress, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, type MowerTaskSubState, type MowerZone, Nodreame, type NodreameDeps, type NodreameEvents, type NodreameOptions, type OssFetchInput, type OssFetcherLike, type PropertyChangedEvent, type PropertyResult, type PropertyState, type PropertyWrite, type RenderMowerSvgOptions, type RenderVacuumPngOptions, type StateChangedEvent, SuctionLevel, TaskStatus, VACUUM_CONSUMABLES, MODEL_CAPABILITIES$1 as VACUUM_MODEL_CAPABILITIES, type VacuumCapabilities, VacuumCapabilityResolver, VacuumDevice, type VacuumGetMapInput, type VacuumMap, WaterVolume, consumableSpec, createClientDumper, createDumper, decodeAiFeature, decodeAutoSwitch, decodeAutoSwitchAll, encodeAiFeatureWrite, encodeAutoSwitchWrite, extractMowerConsumableValues, getMowerCapabilities, getVacuumCapabilities, isDreameConsumableKey, mowerConsumableIndex, mowerFaultSeverity, parseMowerConsumables, parseMowerHeartbeat, parseMowingProgress, renderMowerSvg, renderVacuumPng, resolveCapabilities, supportedAutoSwitchKeys };
+export { AI_FEATURE_BIT, AI_FEATURE_JSON_KEY, AUTO_SWITCH_JSON_KEY, type AiDetectionRaw, type AutoSwitchKey, type AutoSwitchRaw, BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type ConsumableReading, type ConsumableSpec, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceDump, type DeviceEvent, type DreameAiFeature, DreameApiError, DreameAuthError, type DreameCloudState, type DreameConsumableKey, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, type DumperOptions, LIBRARY_NAME, MODEL_CAPABILITIES as MOWER_MODEL_CAPABILITIES, MOWER_TASK_SUBSTATES, type MapBoundingBox, type MapCleanedAreaOverlay, type MapColorScheme, type MapDimensions, type MapFrameType, type MapLayer, type MapLayerType, type MapLowLyingArea, type MapObstacle, type MapPath, type MapPathType, type MapPoint, type MapPose, type MapRestrictedArea, type MapRoom, type MapRoomWall, type MapRun, type MapSegment, type MapStorey, type MapVirtualWall, type MapWallsInfo, type MiotAction, MiotError, type MiotProp, MiotState, type MowerAvailableMap, type MowerCapabilities, MowerCapabilityResolver, MowerChargingStatus, type MowerConsumableKey, type MowerConsumableReading, type MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerFaultSeverity, type MowerHeartbeat, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerMowingProgress, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, type MowerTaskSubState, type MowerZone, Nodreame, type NodreameDeps, type NodreameEvents, type NodreameOptions, type OssFetchInput, type OssFetcherLike, type PropertyChangedEvent, type PropertyResult, type PropertyState, type PropertyWrite, type RenderMowerSvgOptions, type RenderVacuumPngOptions, type StateChangedEvent, SuctionLevel, TaskStatus, VACUUM_CONSUMABLES, MODEL_CAPABILITIES$1 as VACUUM_MODEL_CAPABILITIES, type VacuumCapabilities, VacuumCapabilityResolver, VacuumDevice, type VacuumGetMapInput, type VacuumMap, WaterVolume, consumableSpec, createClientDumper, createDumper, decodeAiFeature, decodeAutoSwitch, decodeAutoSwitchAll, encodeAiFeatureWrite, encodeAutoSwitchWrite, extractMowerConsumableValues, getMowerCapabilities, getVacuumCapabilities, isAuthRefusedError, isDreameConsumableKey, mowerConsumableIndex, mowerFaultSeverity, parseMowerConsumables, parseMowerHeartbeat, parseMowingProgress, renderMowerSvg, renderVacuumPng, resolveCapabilities, supportedAutoSwitchKeys };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/support/version.ts
 var LIBRARY_NAME = "nodedreame";
-var LIBRARY_VERSION = "1.11.9";
+var LIBRARY_VERSION = "1.11.10";
 
 // src/transport/errors.ts
 var DreameError = class extends Error {
@@ -629,6 +629,10 @@ var TypedEmitter = class {
   emit(event, ...args) {
     return this.#emitter.emit(event, ...args);
   }
+  /** Number of listeners registered for `event`. */
+  listenerCount(event) {
+    return this.#emitter.listenerCount(event);
+  }
   removeAllListeners() {
     this.#emitter.removeAllListeners();
     return this;
@@ -641,6 +645,24 @@ function defaultConnect(url, opts) {
   const typed = client;
   return typed;
 }
+function isAuthRefusedError(err) {
+  let cur = err;
+  for (let depth = 0; cur != null && depth < 6; depth += 1) {
+    if (typeof cur !== "object") {
+      break;
+    }
+    const code = cur.code;
+    if (code === 4 || code === 5 || code === 134 || code === 135) {
+      return true;
+    }
+    const message = cur.message;
+    if (typeof message === "string" && /not authorized|bad user ?name|bad username or password|bad password/i.test(message)) {
+      return true;
+    }
+    cur = cur.cause;
+  }
+  return false;
+}
 var DreamePush = class extends TypedEmitter {
   #device;
   #session;
@@ -649,11 +671,15 @@ var DreamePush = class extends TypedEmitter {
   #backoffMs;
   #keepaliveSeconds;
   #rejectUnauthorized;
+  #onAuthFailure;
+  #maxAuthRetries;
   #topic;
   #client = null;
   #closed = false;
   #tearingDown = false;
   #reconnectTimer = null;
+  /** Consecutive auth-refused re-auths since the last successful connect. */
+  #authFailureCount = 0;
   /**
    * Per-instance bound close handler. Stored so we can pass the EXACT same
    * function reference to both `client.on('close', …)` and
@@ -670,6 +696,8 @@ var DreamePush = class extends TypedEmitter {
     this.#backoffMs = input.reconnectBackoffMs ?? 5e3;
     this.#keepaliveSeconds = input.keepaliveSeconds ?? 60;
     this.#rejectUnauthorized = input.rejectUnauthorized ?? false;
+    this.#onAuthFailure = input.onAuthFailure ?? null;
+    this.#maxAuthRetries = input.maxAuthRetries ?? 3;
     this.#topic = buildStatusTopic(this.#device, this.#session.uid, this.#region);
     this.#onClose = () => {
       if (this.#tearingDown) {
@@ -706,7 +734,11 @@ var DreamePush = class extends TypedEmitter {
       this.#reconnectTimer = null;
     }
     await this.#teardownClient();
-    await this.#connectAndSubscribe();
+    try {
+      await this.#connectAndSubscribe();
+    } catch {
+      this.#scheduleReconnect();
+    }
   }
   /** Tear down permanently. Closed subscriptions cannot be reopened. */
   async close() {
@@ -743,6 +775,7 @@ var DreamePush = class extends TypedEmitter {
               reject(new DreameTransportError(`mqtt subscribe failed: ${err.message}`, err));
               return;
             }
+            this.#authFailureCount = 0;
             this.emit("connect");
             resolve();
           });
@@ -776,12 +809,55 @@ var DreamePush = class extends TypedEmitter {
       if (this.#closed || this.#client) {
         return;
       }
-      void this.#connectAndSubscribe().catch((err) => {
-        this.emit("error", err instanceof Error ? err : new DreameTransportError(String(err)));
-        this.#scheduleReconnect();
-      });
+      void this.#attemptReconnect();
     }, this.#backoffMs);
   }
+  /**
+   * One reconnect attempt with reactive auth self-heal. If the broker refuses
+   * the CONNECT with an auth error (a stale access token) and an
+   * `onAuthFailure` provider is wired and the re-auth budget is not exhausted,
+   * mint a fresh session and retry with the new token instead of replaying the
+   * old one. Any other failure (or an exhausted budget) falls back to the plain
+   * backoff reconnect so bad credentials cannot hot-loop re-login.
+   */
+  async #attemptReconnect() {
+    try {
+      await this.#connectAndSubscribe();
+    } catch (err) {
+      if (this.#closed) {
+        return;
+      }
+      if (this.#onAuthFailure && isAuthRefusedError(err) && this.#authFailureCount < this.#maxAuthRetries) {
+        await this.#reauthenticateAndReconnect();
+        return;
+      }
+      this.emit("error", err instanceof Error ? err : new DreameTransportError(String(err)));
+      this.#scheduleReconnect();
+    }
+  }
+  /** Mint a fresh session via `onAuthFailure`, adopt its token, and reconnect. */
+  async #reauthenticateAndReconnect() {
+    this.#authFailureCount += 1;
+    let session;
+    try {
+      session = await this.#onAuthFailure();
+    } catch (err) {
+      this.emit("error", err instanceof Error ? err : new DreameTransportError(String(err)));
+      if (!this.#client) {
+        this.#scheduleReconnect();
+      }
+      return;
+    }
+    if (this.#closed) {
+      return;
+    }
+    this.#session = session;
+    this.#topic = buildStatusTopic(this.#device, this.#session.uid, this.#region);
+    if (this.#client) {
+      return;
+    }
+    void this.#attemptReconnect();
+  }
   async #teardownClient() {
     const client = this.#client;
     this.#client = null;
@@ -957,7 +1033,12 @@ function resolveCapabilities(model) {
 // src/device/base-device.ts
 function defaultBaseDeviceDeps() {
   return {
-    createPush: (device, session, region) => new DreamePush({ device, session, region }),
+    createPush: (device, session, region, onAuthFailure) => new DreamePush({
+      device,
+      session,
+      region,
+      ...onAuthFailure !== void 0 ? { onAuthFailure } : {}
+    }),
     getProperties: (base, props) => getProperties(base, props),
     getCachedProperties: (base, props) => getCachedProperties(base, props),
     setProperties: (base, writes) => setProperties(base, writes),
@@ -969,6 +1050,7 @@ var BaseDevice = class extends TypedEmitter {
   #device;
   #region;
   #sessionRef;
+  #onAuthFailure;
   #deps;
   #fetchInitial;
   #initialProps;
@@ -984,6 +1066,7 @@ var BaseDevice = class extends TypedEmitter {
     this.#device = input.device;
     this.#region = input.region;
     this.#sessionRef = input.sessionRef;
+    this.#onAuthFailure = input.onAuthFailure;
     this.#deps = input.deps ?? defaultBaseDeviceDeps();
     this.#fetchInitial = input.fetchInitialValues ?? true;
     this.#initialProps = input.initialProps ?? [];
@@ -1023,7 +1106,12 @@ var BaseDevice = class extends TypedEmitter {
   }
   /** Open the push, wire events, optionally seed the cache. */
   async start() {
-    const push = this.#deps.createPush(this.#device, this.#sessionRef(), this.#region);
+    const push = this.#deps.createPush(
+      this.#device,
+      this.#sessionRef(),
+      this.#region,
+      this.#onAuthFailure
+    );
     this.#push = push;
     push.on("properties", (changes) => this.#onProperties(changes));
     push.on(
@@ -4863,11 +4951,15 @@ var DEFAULT_HEIGHT = 1200;
 var DEFAULT_PADDING = 50;
 var BACKGROUND = "#f5f5f0";
 var MAP_BOUNDARY = "#006400";
-var MOWING_PATH = "#ffa500";
+var MOWING_PATH = "#32cd32";
 var NAV_PATH = "#b4b4b4";
 var OBSTACLE_STROKE = "#ff4d00";
 var OBSTACLE_FILL = "#ff4d0065";
 var TEXT_COLOR = "#000000";
+var ZONE_LABEL_COLOR = "#3c3c3c";
+function escapeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
 var ZONE_COLORS = [
   ["#a4d291c8", "#86be73"],
   ["#a0c8dcc8", "#82aac8"],
@@ -4990,7 +5082,6 @@ function renderMowerSvg(map, opts = {}) {
     return lines.join("\n");
   }
   const bounds = calculateBounds(allPoints);
-  const multiZone = map.zones.length > 1;
   for (const navPath of map.paths) {
     const dashed = svgPathFromSegments(
       [navPath.path],
@@ -5007,9 +5098,6 @@ function renderMowerSvg(map, opts = {}) {
     }
   }
   map.zones.forEach((zone, i) => {
-    if (!multiZone) {
-      return;
-    }
     const palette = ZONE_COLORS[i % ZONE_COLORS.length];
     const [fill, outline] = palette ?? ZONE_COLORS[0] ?? ["#cccccc", "#888888"];
     const poly = svgPolygon(zone.path, bounds, width, height, padding, fill, outline);
@@ -5018,7 +5106,7 @@ function renderMowerSvg(map, opts = {}) {
     }
   });
   map.zones.forEach((zone, i) => {
-    const outline = multiZone ? ZONE_COLORS[i % ZONE_COLORS.length]?.[1] ?? MAP_BOUNDARY : MAP_BOUNDARY;
+    const outline = ZONE_COLORS[i % ZONE_COLORS.length]?.[1] ?? MAP_BOUNDARY;
     const boundary = svgPathFromSegments(
       [zone.path],
       bounds,
@@ -5062,6 +5150,22 @@ function renderMowerSvg(map, opts = {}) {
       lines.push(poly);
     }
   }
+  for (const zone of map.zones) {
+    if (zone.name.length === 0 || zone.path.length === 0) {
+      continue;
+    }
+    let sumX = 0;
+    let sumY = 0;
+    for (const p of zone.path) {
+      sumX += p.x;
+      sumY += p.y;
+    }
+    const centroid = { x: sumX / zone.path.length, y: sumY / zone.path.length };
+    const { px, py } = coordToPixel(centroid, bounds, width, height, padding);
+    lines.push(
+      `<text x="${px}" y="${py}" font-family="Arial, sans-serif" font-size="20" font-weight="bold" fill="${ZONE_LABEL_COLOR}" text-anchor="middle" dominant-baseline="middle">${escapeXml(zone.name)}</text>`
+    );
+  }
   lines.push("</svg>");
   return lines.join("\n");
 }
@@ -5421,6 +5525,7 @@ function defaultDeps(opts) {
         device: args.device,
         region: args.region,
         sessionRef: args.sessionRef,
+        ...args.onAuthFailure !== void 0 ? { onAuthFailure: args.onAuthFailure } : {},
         ...opts.fetchInitialValues !== void 0 ? { fetchInitialValues: opts.fetchInitialValues } : {},
         ...opts.pollIntervalMs !== void 0 ? { pollIntervalMs: opts.pollIntervalMs } : {}
       });
@@ -5434,6 +5539,15 @@ var Nodreame = class extends TypedEmitter {
   #session = null;
   #devices = [];
   #closed = false;
+  /** Background timer that proactively refreshes before the token expires. */
+  #refreshTimer = null;
+  /** Guard against overlapping proactive-refresh runs. */
+  #refreshInFlight = false;
+  /**
+   * The single in-flight refresh, shared by concurrent callers so the proactive
+   * timer and a manual `ensureSession()`/`reauthenticate()` never double-refresh.
+   */
+  #inFlightRefresh = null;
   constructor(opts, deps) {
     super();
     if (!opts.username || !opts.password) {
@@ -5462,6 +5576,7 @@ var Nodreame = class extends TypedEmitter {
       ...this.#opts.lang !== void 0 ? { lang: this.#opts.lang } : {},
       ...this.#opts.fetchImpl !== void 0 ? { fetchImpl: this.#opts.fetchImpl } : {}
     });
+    this.#scheduleProactiveRefresh();
     return this.#session;
   }
   /** Return a valid session, refreshing proactively within the leeway window. */
@@ -5473,18 +5588,61 @@ var Nodreame = class extends TypedEmitter {
     if (Date.now() < current.expiresAt - this.#leewayMs) {
       return current;
     }
+    return this.#refreshNow(current);
+  }
+  /**
+   * Force a session refresh REGARDLESS of the current expiry, then propagate the
+   * new token to every live device push. Wired as each push's `onAuthFailure`:
+   * when a broker refuses a CONNECT because it considers the token stale (even
+   * though {@link ensureSession} still thinks it valid — e.g. server-side early
+   * revocation or clock skew), this mints a genuinely fresh token instead of
+   * replaying the rejected one.
+   */
+  async reauthenticate() {
+    if (this.#closed) {
+      throw new DreameAuthError("client is closed");
+    }
+    const current = this.#session;
+    if (!current) {
+      return this.login();
+    }
+    return this.#refreshNow(current);
+  }
+  /**
+   * Refresh via the refresh-token (with a full re-login fallback) and propagate
+   * the new token to every device push. Shared by {@link ensureSession} (within
+   * the leeway window) and {@link reauthenticate} (unconditional).
+   */
+  async #refreshNow(current) {
+    const existing = this.#inFlightRefresh;
+    if (existing) {
+      return existing;
+    }
+    const run = this.#doRefresh(current);
+    this.#inFlightRefresh = run;
+    try {
+      return await run;
+    } finally {
+      this.#inFlightRefresh = null;
+    }
+  }
+  async #doRefresh(current) {
     if (current.refreshToken) {
+      let next = null;
       try {
-        const next = await this.#deps.refresh({
+        next = await this.#deps.refresh({
           refreshToken: current.refreshToken,
           region: this.#opts.region,
           ...this.#opts.country !== void 0 ? { country: this.#opts.country } : {},
           ...this.#opts.lang !== void 0 ? { lang: this.#opts.lang } : {},
           ...this.#opts.fetchImpl !== void 0 ? { fetchImpl: this.#opts.fetchImpl } : {}
         });
+      } catch {
+        next = null;
+      }
+      if (next) {
         await this.#adoptSession(next);
         return next;
-      } catch {
       }
     }
     const fresh = await this.login();
@@ -5506,23 +5664,30 @@ var Nodreame = class extends TypedEmitter {
       (device) => this.#deps.createDevice({
         device,
         region: this.#opts.region,
-        sessionRef: () => this.#requireSession()
+        sessionRef: () => this.#requireSession(),
+        onAuthFailure: () => this.reauthenticate()
       })
     );
     for (const h of handles) {
       h.on("stateChanged", (e) => this.emit("stateChanged", e));
       h.on("event", (e) => this.emit("event", e));
-      h.on("error", (err) => this.emit("error", err));
+      h.on("error", (err) => {
+        if (this.listenerCount("error") > 0) {
+          this.emit("error", err);
+        }
+      });
       await h.start();
     }
     const previous = this.#devices;
     this.#devices = [...handles];
     await Promise.all(previous.map((d) => d.close()));
+    this.#scheduleProactiveRefresh();
     return this.#devices;
   }
   /** Tear everything down: close every device push and clear timers. */
   async close() {
     this.#closed = true;
+    this.#clearRefreshTimer();
     const devices = this.#devices;
     this.#devices = [];
     await Promise.all(devices.map((d) => d.close()));
@@ -5537,13 +5702,65 @@ var Nodreame = class extends TypedEmitter {
   async #adoptSession(session) {
     this.#session = session;
     await this.#propagateSession(session);
+    this.#scheduleProactiveRefresh();
+  }
+  #clearRefreshTimer() {
+    if (this.#refreshTimer) {
+      clearTimeout(this.#refreshTimer);
+      this.#refreshTimer = null;
+    }
+  }
+  /** Arm the proactive-refresh timer `delayMs` from now (clamped to ≥0). */
+  #armRefreshTimer(delayMs) {
+    this.#clearRefreshTimer();
+    if (this.#closed) {
+      return;
+    }
+    this.#refreshTimer = setTimeout(() => {
+      this.#refreshTimer = null;
+      void this.#runProactiveRefresh();
+    }, Math.max(0, delayMs));
+  }
+  /** (Re)arm the proactive-refresh timer against the current session's expiry. */
+  #scheduleProactiveRefresh() {
+    const session = this.#session;
+    if (!session) {
+      this.#clearRefreshTimer();
+      return;
+    }
+    this.#armRefreshTimer(session.expiresAt - this.#leewayMs - Date.now());
+  }
+  /**
+   * Timer body: refresh the session before it expires, then reschedule against
+   * the new expiry. Because {@link ensureSession} propagates the refreshed token
+   * to every device push, each MQTT connection is re-keyed BEFORE the broker
+   * would reject the old one — the reactive re-auth loop never even starts.
+   */
+  async #runProactiveRefresh() {
+    if (this.#closed || this.#refreshInFlight) {
+      return;
+    }
+    this.#refreshInFlight = true;
+    try {
+      await this.ensureSession();
+      this.#refreshInFlight = false;
+      this.#scheduleProactiveRefresh();
+    } catch (err) {
+      this.#refreshInFlight = false;
+      if (this.listenerCount("error") > 0) {
+        this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      }
+      if (!this.#closed) {
+        this.#armRefreshTimer(this.#leewayMs);
+      }
+    }
   }
   /** Push the refreshed token to every live device push. */
   async #propagateSession(session) {
     if (this.#closed) {
       return;
     }
-    await Promise.all(this.#devices.map((d) => d.applySession(session)));
+    await Promise.allSettled(this.#devices.map((d) => d.applySession(session)));
   }
 };
 
@@ -6045,6 +6262,7 @@ export {
   extractMowerConsumableValues,
   getMowerCapabilities,
   getVacuumCapabilities,
+  isAuthRefusedError,
   isDreameConsumableKey,
   mowerConsumableIndex,
   mowerFaultSeverity,