@apocaliss92/nodedreame 1.6.1 → 1.7.1

package/dist/index.d.cts

@@ -755,6 +755,52 @@ declare function decodeAiFeature(raw: AiDetectionRaw, feature: DreameAiFeature):
  */
 declare function encodeAiFeatureWrite(raw: AiDetectionRaw, feature: DreameAiFeature, value: boolean): number | string;
 
+/**
+ * Vacuum consumable/maintenance map (ported from Tasshack `dreame-vacuum`
+ * v2.0.0b25 — property + action mappings). Each consumable lives on its own MIoT
+ * service `siid`: a remaining-life `%` property (`siid/piid`) and a "reset to
+ * 100%" action (`siid/aiid 1`). A model exposes only a SUBSET — which is
+ * discovered by PRESENCE (the device reports the life property) rather than a
+ * hardcoded per-model list, mirroring how the HA integration derives support.
+ */
+/** Stable consumable keys (kebab-case so a consumer can use them verbatim). */
+type DreameConsumableKey = 'main-brush' | 'side-brush' | 'filter' | 'sensor' | 'tank-filter' | 'mop-pad' | 'silver-ion' | 'detergent' | 'squeegee' | 'dust-bag';
+/** One consumable's wire coordinates: remaining-life property + optional reset action. */
+interface ConsumableSpec {
+    readonly key: DreameConsumableKey;
+    readonly label: string;
+    /** Remaining-life % property (0..100). */
+    readonly life: {
+        readonly siid: number;
+        readonly piid: number;
+    };
+    /** "Mark replaced / reset life" action, or null when the model exposes none. */
+    readonly reset: {
+        readonly siid: number;
+        readonly aiid: number;
+    } | null;
+}
+/**
+ * Every consumable nodedreame knows. The reset action shares the consumable's
+ * service `siid` with `aiid 1` (Tasshack action map). `dust-bag` has a life
+ * property but no reset action.
+ */
+declare const VACUUM_CONSUMABLES: readonly ConsumableSpec[];
+/** Lookup a consumable spec by key (undefined for an unknown key). */
+declare function consumableSpec(key: DreameConsumableKey): ConsumableSpec | undefined;
+/** Narrow an arbitrary string to a known {@link DreameConsumableKey} — lets a
+ *  string-keyed consumer (e.g. a generic consumables cap) validate before
+ *  calling the typed reset path with no cast. */
+declare function isDreameConsumableKey(key: string): key is DreameConsumableKey;
+/** A resolved consumable reading: which consumable, its remaining life %, and
+ *  whether a reset action exists. Only the consumables the model REPORTS appear. */
+interface ConsumableReading {
+    readonly key: DreameConsumableKey;
+    readonly label: string;
+    readonly leftPct: number;
+    readonly resettable: boolean;
+}
+
 /**
  * Per-model vacuum capability records (ported from malard/node-dreame
  * src/capabilities.ts, MIT — attribution retained) plus a resolver that
@@ -1266,6 +1312,33 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
     get sideBrushLeftPct(): number | null;
     get filterLeftPct(): number | null;
     get volume(): number | null;
+    /**
+     * Remaining-life % (0..100) for one consumable, or `null` when the model does
+     * not report it (presence == support). Call {@link refreshConsumables} first
+     * on a docked robot so the cloud-shadow life values are seeded.
+     */
+    consumableLeftPct(key: DreameConsumableKey): number | null;
+    /**
+     * The consumables this model EXPOSES — discovered by presence (a reported
+     * life property), mirroring how the HA integration derives support. Each
+     * reading carries the current remaining-life % and whether a reset action
+     * exists. Empty until the life properties have been observed (push) or seeded
+     * via {@link refreshConsumables}.
+     */
+    get supportedConsumables(): readonly ConsumableReading[];
+    /**
+     * Seed EVERY consumable life property from the cloud shadow (no robot wake) so
+     * {@link supportedConsumables} reflects the full set on a docked robot. The
+     * consumable life values are static settings the robot rarely re-pushes over
+     * MQTT, so a fresh connect surfaces only the actively-changing ones without this.
+     */
+    refreshConsumables(): Promise<void>;
+    /**
+     * Reset (mark replaced → life back to 100%) one consumable via its MIoT reset
+     * action. Rejects when the model exposes no reset action for the key (e.g.
+     * `dust-bag`) or the key is unknown.
+     */
+    resetConsumable(key: DreameConsumableKey): Promise<unknown>;
     /**
      * The raw `AI_DETECTION` value (siid 4 piid 22) — an int bitmask or a JSON
      * string, depending on firmware — or `null` when not yet observed. Prefer the
@@ -2245,4 +2318,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, type AiDetectionRaw, BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceDump, type DeviceEvent, type DreameAiFeature, DreameApiError, DreameAuthError, type DreameCloudState, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, type DumperOptions, LIBRARY_NAME, MODEL_CAPABILITIES as MOWER_MODEL_CAPABILITIES, type MapBoundingBox, type MapCleanedAreaOverlay, 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 MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, 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, MODEL_CAPABILITIES$1 as VACUUM_MODEL_CAPABILITIES, type VacuumCapabilities, VacuumCapabilityResolver, VacuumDevice, type VacuumGetMapInput, type VacuumMap, WaterVolume, createClientDumper, createDumper, decodeAiFeature, encodeAiFeatureWrite, getMowerCapabilities, getVacuumCapabilities, renderMowerSvg, renderVacuumPng, resolveCapabilities };
+export { AI_FEATURE_BIT, AI_FEATURE_JSON_KEY, type AiDetectionRaw, 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, type MapBoundingBox, type MapCleanedAreaOverlay, 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 MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, 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, encodeAiFeatureWrite, getMowerCapabilities, getVacuumCapabilities, isDreameConsumableKey, renderMowerSvg, renderVacuumPng, resolveCapabilities };

package/dist/index.d.ts

@@ -755,6 +755,52 @@ declare function decodeAiFeature(raw: AiDetectionRaw, feature: DreameAiFeature):
  */
 declare function encodeAiFeatureWrite(raw: AiDetectionRaw, feature: DreameAiFeature, value: boolean): number | string;
 
+/**
+ * Vacuum consumable/maintenance map (ported from Tasshack `dreame-vacuum`
+ * v2.0.0b25 — property + action mappings). Each consumable lives on its own MIoT
+ * service `siid`: a remaining-life `%` property (`siid/piid`) and a "reset to
+ * 100%" action (`siid/aiid 1`). A model exposes only a SUBSET — which is
+ * discovered by PRESENCE (the device reports the life property) rather than a
+ * hardcoded per-model list, mirroring how the HA integration derives support.
+ */
+/** Stable consumable keys (kebab-case so a consumer can use them verbatim). */
+type DreameConsumableKey = 'main-brush' | 'side-brush' | 'filter' | 'sensor' | 'tank-filter' | 'mop-pad' | 'silver-ion' | 'detergent' | 'squeegee' | 'dust-bag';
+/** One consumable's wire coordinates: remaining-life property + optional reset action. */
+interface ConsumableSpec {
+    readonly key: DreameConsumableKey;
+    readonly label: string;
+    /** Remaining-life % property (0..100). */
+    readonly life: {
+        readonly siid: number;
+        readonly piid: number;
+    };
+    /** "Mark replaced / reset life" action, or null when the model exposes none. */
+    readonly reset: {
+        readonly siid: number;
+        readonly aiid: number;
+    } | null;
+}
+/**
+ * Every consumable nodedreame knows. The reset action shares the consumable's
+ * service `siid` with `aiid 1` (Tasshack action map). `dust-bag` has a life
+ * property but no reset action.
+ */
+declare const VACUUM_CONSUMABLES: readonly ConsumableSpec[];
+/** Lookup a consumable spec by key (undefined for an unknown key). */
+declare function consumableSpec(key: DreameConsumableKey): ConsumableSpec | undefined;
+/** Narrow an arbitrary string to a known {@link DreameConsumableKey} — lets a
+ *  string-keyed consumer (e.g. a generic consumables cap) validate before
+ *  calling the typed reset path with no cast. */
+declare function isDreameConsumableKey(key: string): key is DreameConsumableKey;
+/** A resolved consumable reading: which consumable, its remaining life %, and
+ *  whether a reset action exists. Only the consumables the model REPORTS appear. */
+interface ConsumableReading {
+    readonly key: DreameConsumableKey;
+    readonly label: string;
+    readonly leftPct: number;
+    readonly resettable: boolean;
+}
+
 /**
  * Per-model vacuum capability records (ported from malard/node-dreame
  * src/capabilities.ts, MIT — attribution retained) plus a resolver that
@@ -1266,6 +1312,33 @@ declare class VacuumDevice extends BaseDevice<VacuumDeviceEvents> {
     get sideBrushLeftPct(): number | null;
     get filterLeftPct(): number | null;
     get volume(): number | null;
+    /**
+     * Remaining-life % (0..100) for one consumable, or `null` when the model does
+     * not report it (presence == support). Call {@link refreshConsumables} first
+     * on a docked robot so the cloud-shadow life values are seeded.
+     */
+    consumableLeftPct(key: DreameConsumableKey): number | null;
+    /**
+     * The consumables this model EXPOSES — discovered by presence (a reported
+     * life property), mirroring how the HA integration derives support. Each
+     * reading carries the current remaining-life % and whether a reset action
+     * exists. Empty until the life properties have been observed (push) or seeded
+     * via {@link refreshConsumables}.
+     */
+    get supportedConsumables(): readonly ConsumableReading[];
+    /**
+     * Seed EVERY consumable life property from the cloud shadow (no robot wake) so
+     * {@link supportedConsumables} reflects the full set on a docked robot. The
+     * consumable life values are static settings the robot rarely re-pushes over
+     * MQTT, so a fresh connect surfaces only the actively-changing ones without this.
+     */
+    refreshConsumables(): Promise<void>;
+    /**
+     * Reset (mark replaced → life back to 100%) one consumable via its MIoT reset
+     * action. Rejects when the model exposes no reset action for the key (e.g.
+     * `dust-bag`) or the key is unknown.
+     */
+    resetConsumable(key: DreameConsumableKey): Promise<unknown>;
     /**
      * The raw `AI_DETECTION` value (siid 4 piid 22) — an int bitmask or a JSON
      * string, depending on firmware — or `null` when not yet observed. Prefer the
@@ -2245,4 +2318,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, type AiDetectionRaw, BaseDevice, type BaseDeviceEvents, type BatchDeviceDataFetcher, type CapabilityResolver, ChargingStatus, type CleanOpts, CleaningMode, type CreateDeviceArgs, DefaultCapabilityResolver, type DeviceCapabilities, type DeviceDump, type DeviceEvent, type DreameAiFeature, DreameApiError, DreameAuthError, type DreameCloudState, type DreameDevice, DreameDeviceOfflineError, DreameError, type DreameRegion, type DreameSession, DreameTransportError, type DumperOptions, LIBRARY_NAME, MODEL_CAPABILITIES as MOWER_MODEL_CAPABILITIES, type MapBoundingBox, type MapCleanedAreaOverlay, 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 MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, 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, MODEL_CAPABILITIES$1 as VACUUM_MODEL_CAPABILITIES, type VacuumCapabilities, VacuumCapabilityResolver, VacuumDevice, type VacuumGetMapInput, type VacuumMap, WaterVolume, createClientDumper, createDumper, decodeAiFeature, encodeAiFeatureWrite, getMowerCapabilities, getVacuumCapabilities, renderMowerSvg, renderVacuumPng, resolveCapabilities };
+export { AI_FEATURE_BIT, AI_FEATURE_JSON_KEY, type AiDetectionRaw, 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, type MapBoundingBox, type MapCleanedAreaOverlay, 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 MowerContour, MowerControlAction, type MowerControlState, MowerDevice, type MowerDeviceInput, MowerFault, type MowerMap, type MowerMapBoundary, type MowerMowPath, type MowerPathEntry, type MowerPoint, type MowerSpotArea, MowerStatus, type MowerTaskDescriptor, MowerTaskStatus, 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, encodeAiFeatureWrite, getMowerCapabilities, getVacuumCapabilities, isDreameConsumableKey, renderMowerSvg, renderVacuumPng, resolveCapabilities };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/support/version.ts
 var LIBRARY_NAME = "nodedreame";
-var LIBRARY_VERSION = "1.6.1";
+var LIBRARY_VERSION = "1.7.1";
 
 // src/transport/errors.ts
 var DreameError = class extends Error {
@@ -1570,6 +1570,26 @@ function encodeAiFeatureWrite(raw, feature, value) {
   );
 }
 
+// src/models/vacuum/consumables.ts
+var VACUUM_CONSUMABLES = [
+  { key: "main-brush", label: "Main Brush", life: { siid: 9, piid: 2 }, reset: { siid: 9, aiid: 1 } },
+  { key: "side-brush", label: "Side Brush", life: { siid: 10, piid: 2 }, reset: { siid: 10, aiid: 1 } },
+  { key: "filter", label: "Filter", life: { siid: 11, piid: 1 }, reset: { siid: 11, aiid: 1 } },
+  { key: "sensor", label: "Sensor", life: { siid: 16, piid: 1 }, reset: { siid: 16, aiid: 1 } },
+  { key: "tank-filter", label: "Tank Filter", life: { siid: 17, piid: 1 }, reset: { siid: 17, aiid: 1 } },
+  { key: "mop-pad", label: "Mop Pad", life: { siid: 18, piid: 1 }, reset: { siid: 18, aiid: 1 } },
+  { key: "silver-ion", label: "Silver-ion", life: { siid: 19, piid: 2 }, reset: { siid: 19, aiid: 1 } },
+  { key: "detergent", label: "Detergent", life: { siid: 20, piid: 1 }, reset: { siid: 20, aiid: 1 } },
+  { key: "squeegee", label: "Squeegee", life: { siid: 24, piid: 1 }, reset: { siid: 24, aiid: 1 } },
+  { key: "dust-bag", label: "Dust Bag", life: { siid: 27, piid: 17 }, reset: null }
+];
+function consumableSpec(key2) {
+  return VACUUM_CONSUMABLES.find((c) => c.key === key2);
+}
+function isDreameConsumableKey(key2) {
+  return VACUUM_CONSUMABLES.some((c) => c.key === key2);
+}
+
 // src/models/vacuum/capabilities.ts
 var X50_AI_FEATURES = [
   "obstacleDetection",
@@ -2771,6 +2791,51 @@ var VacuumDevice = class _VacuumDevice extends BaseDevice {
   get volume() {
     return this.#num(SETTINGS_PROP.VOLUME.siid, SETTINGS_PROP.VOLUME.piid);
   }
+  // -- consumables --------------------------------------------------------
+  /**
+   * Remaining-life % (0..100) for one consumable, or `null` when the model does
+   * not report it (presence == support). Call {@link refreshConsumables} first
+   * on a docked robot so the cloud-shadow life values are seeded.
+   */
+  consumableLeftPct(key2) {
+    const spec = consumableSpec(key2);
+    if (spec === void 0) return null;
+    return this.#num(spec.life.siid, spec.life.piid);
+  }
+  /**
+   * The consumables this model EXPOSES — discovered by presence (a reported
+   * life property), mirroring how the HA integration derives support. Each
+   * reading carries the current remaining-life % and whether a reset action
+   * exists. Empty until the life properties have been observed (push) or seeded
+   * via {@link refreshConsumables}.
+   */
+  get supportedConsumables() {
+    return VACUUM_CONSUMABLES.flatMap((spec) => {
+      const leftPct = this.#num(spec.life.siid, spec.life.piid);
+      return leftPct === null ? [] : [{ key: spec.key, label: spec.label, leftPct, resettable: spec.reset !== null }];
+    });
+  }
+  /**
+   * Seed EVERY consumable life property from the cloud shadow (no robot wake) so
+   * {@link supportedConsumables} reflects the full set on a docked robot. The
+   * consumable life values are static settings the robot rarely re-pushes over
+   * MQTT, so a fresh connect surfaces only the actively-changing ones without this.
+   */
+  async refreshConsumables() {
+    await this.refreshCachedProperties(VACUUM_CONSUMABLES.map((c) => c.life));
+  }
+  /**
+   * Reset (mark replaced → life back to 100%) one consumable via its MIoT reset
+   * action. Rejects when the model exposes no reset action for the key (e.g.
+   * `dust-bag`) or the key is unknown.
+   */
+  async resetConsumable(key2) {
+    const spec = consumableSpec(key2);
+    if (spec === void 0 || spec.reset === null) {
+      throw new DreameError(`resetConsumable: no reset action for consumable "${key2}"`);
+    }
+    return this.callAction(spec.reset.siid, spec.reset.aiid, []);
+  }
   // -- AI obstacle-detection ----------------------------------------------
   /**
    * The raw `AI_DETECTION` value (siid 4 piid 22) — an int bitmask or a JSON
@@ -4755,16 +4820,19 @@ export {
   Nodreame,
   SuctionLevel,
   TaskStatus,
+  VACUUM_CONSUMABLES,
   MODEL_CAPABILITIES as VACUUM_MODEL_CAPABILITIES,
   VacuumCapabilityResolver,
   VacuumDevice,
   WaterVolume,
+  consumableSpec,
   createClientDumper,
   createDumper,
   decodeAiFeature,
   encodeAiFeatureWrite,
   getMowerCapabilities,
   getVacuumCapabilities,
+  isDreameConsumableKey,
   renderMowerSvg,
   renderVacuumPng,
   resolveCapabilities