@apocaliss92/nodedreame 1.3.1 → 1.5.0

package/dist/index.d.cts

@@ -1272,6 +1272,36 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
     refreshFromCache(): Promise<void>;
     /** The most-recently-decoded map, or `null` until {@link getMap} succeeds. */
     get lastMap(): VacuumMap | null;
+    /**
+     * The OSS object name of the latest map frame the robot advertised via its
+     * PATH push (siid 6 piid 3), or `null` when none has been observed yet (the
+     * robot has not uploaded a map since connect). This is the `filename` to pass
+     * to {@link getMap} — or just call {@link fetchLatestMap}.
+     */
+    get mapFilename(): string | null;
+    /**
+     * Convenience: fetch + decode the LATEST map frame the robot advertised,
+     * reading {@link mapFilename} and delegating to {@link getMap}. Returns `null`
+     * when no map filename has been observed yet (vs throwing) so a consumer can
+     * poll it safely; once a filename is present it behaves exactly like
+     * {@link getMap} (capability-gated on `canMap`, caches {@link lastMap}, emits
+     * `'map'`). The `fetcher`/`key`/`iv`/`host`/`timeoutMs`/`signal` overrides are
+     * forwarded verbatim.
+     */
+    fetchLatestMap(opts?: Omit<VacuumGetMapInput, 'filename'>): Promise<VacuumMap | null>;
+    /**
+     * Seed {@link mapFilename} from the CLOUD SHADOW (the last value the robot
+     * pushed for siid 6 piid 3) WITHOUT waking it — so a docked/idle robot can
+     * surface its LAST cleaning map without a fresh clean. Emits the usual
+     * `propertyChanged`/`stateChanged` (so a map-watching consumer re-renders) and
+     * returns the resolved {@link mapFilename} (null when the model has no map or
+     * the shadow carries no map path yet).
+     *
+     * NOTE: the shadow holds the last LIVE-PATH filename; its OSS blob may have
+     * expired, in which case a follow-up {@link fetchLatestMap} rejects — treat
+     * that as "no saved map available".
+     */
+    refreshSavedMapFilename(): Promise<string | null>;
     /**
      * The current room/segment id, derived from the most-recently-decoded map's
      * active-segment set (`sa`). `null` when no map has been fetched or no

package/dist/index.d.ts

@@ -1272,6 +1272,36 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
     refreshFromCache(): Promise<void>;
     /** The most-recently-decoded map, or `null` until {@link getMap} succeeds. */
     get lastMap(): VacuumMap | null;
+    /**
+     * The OSS object name of the latest map frame the robot advertised via its
+     * PATH push (siid 6 piid 3), or `null` when none has been observed yet (the
+     * robot has not uploaded a map since connect). This is the `filename` to pass
+     * to {@link getMap} — or just call {@link fetchLatestMap}.
+     */
+    get mapFilename(): string | null;
+    /**
+     * Convenience: fetch + decode the LATEST map frame the robot advertised,
+     * reading {@link mapFilename} and delegating to {@link getMap}. Returns `null`
+     * when no map filename has been observed yet (vs throwing) so a consumer can
+     * poll it safely; once a filename is present it behaves exactly like
+     * {@link getMap} (capability-gated on `canMap`, caches {@link lastMap}, emits
+     * `'map'`). The `fetcher`/`key`/`iv`/`host`/`timeoutMs`/`signal` overrides are
+     * forwarded verbatim.
+     */
+    fetchLatestMap(opts?: Omit<VacuumGetMapInput, 'filename'>): Promise<VacuumMap | null>;
+    /**
+     * Seed {@link mapFilename} from the CLOUD SHADOW (the last value the robot
+     * pushed for siid 6 piid 3) WITHOUT waking it — so a docked/idle robot can
+     * surface its LAST cleaning map without a fresh clean. Emits the usual
+     * `propertyChanged`/`stateChanged` (so a map-watching consumer re-renders) and
+     * returns the resolved {@link mapFilename} (null when the model has no map or
+     * the shadow carries no map path yet).
+     *
+     * NOTE: the shadow holds the last LIVE-PATH filename; its OSS blob may have
+     * expired, in which case a follow-up {@link fetchLatestMap} rejects — treat
+     * that as "no saved map available".
+     */
+    refreshSavedMapFilename(): Promise<string | null>;
     /**
      * The current room/segment id, derived from the most-recently-decoded map's
      * active-segment set (`sa`). `null` when no map has been fetched or no

package/dist/index.js

@@ -1152,7 +1152,14 @@ var VACUUM_PROP = {
   /** VERIFIED r2532a 2026-05-03 — task progress percentage 0..100. */
   TASK_PROGRESS_PCT: { siid: 4, piid: 63 },
   /** VERIFIED r2532a — mop-drying progress (minutes ticking during MopDrying). */
-  DRYING_PROGRESS: { siid: 4, piid: 64 }
+  DRYING_PROGRESS: { siid: 4, piid: 64 },
+  /**
+   * Map "PATH" push — the OSS object name of the latest map frame the robot
+   * uploaded (the value passed to {@link VacuumDevice.getMap}). Arrives via the
+   * MQTT push during/after cleaning; NOT in `DEFAULT_PROPS` because it is not
+   * polled (it is pushed). Read it through {@link VacuumDevice.mapFilename}.
+   */
+  MAP_PATH: { siid: 6, piid: 3 }
 };
 var VACUUM_ACTION = {
   /** ASSUMED Tasshack — start cleaning. */
@@ -2808,6 +2815,47 @@ var VacuumDevice = class _VacuumDevice extends BaseDevice {
   get lastMap() {
     return this.#lastMap;
   }
+  /**
+   * The OSS object name of the latest map frame the robot advertised via its
+   * PATH push (siid 6 piid 3), or `null` when none has been observed yet (the
+   * robot has not uploaded a map since connect). This is the `filename` to pass
+   * to {@link getMap} — or just call {@link fetchLatestMap}.
+   */
+  get mapFilename() {
+    const v = this.getProperty(VACUUM_PROP.MAP_PATH.siid, VACUUM_PROP.MAP_PATH.piid)?.value;
+    return typeof v === "string" && v.length > 0 ? v : null;
+  }
+  /**
+   * Convenience: fetch + decode the LATEST map frame the robot advertised,
+   * reading {@link mapFilename} and delegating to {@link getMap}. Returns `null`
+   * when no map filename has been observed yet (vs throwing) so a consumer can
+   * poll it safely; once a filename is present it behaves exactly like
+   * {@link getMap} (capability-gated on `canMap`, caches {@link lastMap}, emits
+   * `'map'`). The `fetcher`/`key`/`iv`/`host`/`timeoutMs`/`signal` overrides are
+   * forwarded verbatim.
+   */
+  async fetchLatestMap(opts = {}) {
+    const filename = this.mapFilename;
+    if (filename === null) return null;
+    return this.getMap({ filename, ...opts });
+  }
+  /**
+   * Seed {@link mapFilename} from the CLOUD SHADOW (the last value the robot
+   * pushed for siid 6 piid 3) WITHOUT waking it — so a docked/idle robot can
+   * surface its LAST cleaning map without a fresh clean. Emits the usual
+   * `propertyChanged`/`stateChanged` (so a map-watching consumer re-renders) and
+   * returns the resolved {@link mapFilename} (null when the model has no map or
+   * the shadow carries no map path yet).
+   *
+   * NOTE: the shadow holds the last LIVE-PATH filename; its OSS blob may have
+   * expired, in which case a follow-up {@link fetchLatestMap} rejects — treat
+   * that as "no saved map available".
+   */
+  async refreshSavedMapFilename() {
+    if (!this.#caps.canMap) return null;
+    await this.refreshCachedProperties([VACUUM_PROP.MAP_PATH]);
+    return this.mapFilename;
+  }
   /**
    * The current room/segment id, derived from the most-recently-decoded map's
    * active-segment set (`sa`). `null` when no map has been fetched or no