@apocaliss92/nodedreame 1.2.0 → 1.3.1

package/README.md

@@ -288,6 +288,54 @@ parser and SVG renderer from
 [antondaubert/dreame-mower](https://github.com/antondaubert/dreame-mower). Both
 are MIT — see `LICENSE`.
 
+## Diagnostic dump (read-only)
+
+`nodedreame` can record what a device exposes while it operates and export an
+**anonymized** JSON you can attach to a GitHub issue to help map undocumented
+codes (e.g. mower `taskStatus` 2/3/10/13). The dumper is strictly **read-only** —
+it never sends a command and never wakes the robot to act. It only subscribes to
+the device's event stream (`on`/`off`), reads the cache (`getProperty`), and
+pulls the cloud shadow (`refreshFromCache`).
+
+```ts
+import { Nodreame, createDumper } from '@apocaliss92/nodedreame';
+
+const client = new Nodreame({ username, password, region: 'eu' });
+await client.login();
+const [device] = await client.discoverDevices();
+
+const dumper = createDumper(device);
+await dumper.start(); // hooks the live stream + periodic cloud-shadow read
+// ...operate the device normally for a few minutes...
+await dumper.stop();
+
+console.log(dumper.exportJson()); // pretty, anonymized — safe to share
+await client.close();
+```
+
+What it captures: per-property distinct value-sets with an `unmapped` flag
+(values that match no known enum — the highest-value signal), MIoT events, and a
+static command/capability catalog. What it strips: device/account ids, tokens,
+MAC, serial, Wi-Fi/IP, GPS, room names, and any custom device name (all →
+`[redacted]`). `firmware`/`region` are omitted (not surfaced by the device
+handle yet).
+
+Dump a whole account at once with `createClientDumper(client)`, which returns one
+dumper per discovered device:
+
+```ts
+import { createClientDumper } from '@apocaliss92/nodedreame';
+
+const dumpers = createClientDumper(client);
+await Promise.all(dumpers.map((d) => d.start()));
+// ...observe...
+await Promise.all(dumpers.map((d) => d.stop()));
+const dumps = dumpers.map((d) => d.exportJson());
+```
+
+Share the exported JSON in a library issue — maintainers diff it against the enum
+tables to label new codes and fold them into the library.
+
 ## Install
 
 ```bash

package/dist/index.cjs

@@ -57,6 +57,8 @@ __export(index_exports, {
   VacuumCapabilityResolver: () => VacuumCapabilityResolver,
   VacuumDevice: () => VacuumDevice,
   WaterVolume: () => WaterVolume,
+  createClientDumper: () => createClientDumper,
+  createDumper: () => createDumper,
   getMowerCapabilities: () => getMowerCapabilities,
   getVacuumCapabilities: () => getVacuumCapabilities,
   renderMowerSvg: () => renderMowerSvg,
@@ -67,6 +69,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/support/version.ts
 var LIBRARY_NAME = "nodedreame";
+var LIBRARY_VERSION = "1.3.1";
 
 // src/transport/errors.ts
 var DreameError = class extends Error {
@@ -2836,11 +2839,11 @@ var VacuumDevice = class _VacuumDevice extends BaseDevice {
     }
     this.#requireCap(this.#caps.canCleanPerRoom, "cleanZones", "per-room cleaning");
     const { repeats, fan, water } = this.#resolveCleanOpts(opts);
-    const areas = zones.map((z3) => [
-      Math.round(z3.x0),
-      Math.round(z3.y0),
-      Math.round(z3.x1),
-      Math.round(z3.y1),
+    const areas = zones.map((z4) => [
+      Math.round(z4.x0),
+      Math.round(z4.y0),
+      Math.round(z4.x1),
+      Math.round(z4.y1),
       repeats,
       fan,
       water
@@ -3925,7 +3928,7 @@ var MowerDevice = class _MowerDevice extends BaseDevice {
     if (zoneIds.length === 0) {
       throw new RangeError("startMowingZones: zoneIds must not be empty");
     }
-    return this.#sendTask(buildZonePayload(zoneIds.map((z3) => Math.trunc(z3))));
+    return this.#sendTask(buildZonePayload(zoneIds.map((z4) => Math.trunc(z4))));
   }
   /** Edge / contour mowing (2:50 o:101). Contour ids are two-int pairs [[1,0]]. */
   async startMowingEdges(contourIds) {
@@ -4149,6 +4152,461 @@ var Nodreame = class extends TypedEmitter {
     await Promise.all(this.#devices.map((d) => d.applySession(session)));
   }
 };
+
+// src/diagnostics/redact.ts
+var REDACTED = "[redacted]";
+var SENSITIVE_KEY_FRAGMENTS = [
+  // identity / secrets
+  "did",
+  // `deviceid` is listed explicitly: the bare `did` fragment does NOT match
+  // `deviceid` (the substring `did` is absent from `d-e-v-i-c-e-i-d`), yet
+  // base-device sets the real `did` as `deviceId` on raw payloads (FIX 1).
+  "deviceid",
+  "uid",
+  "token",
+  // accessToken, refreshToken, refresh_token, token_type stripped too (safe)
+  "mac",
+  "serial",
+  "email",
+  "account",
+  "password",
+  "passwd",
+  "secret",
+  "authorization",
+  "auth",
+  "credential",
+  "apikey",
+  "api_key",
+  "clientid",
+  "client_id",
+  // location / PII
+  "gps",
+  "coordinate",
+  "latitude",
+  "longitude",
+  "lat",
+  "lon",
+  "lng",
+  "ssid",
+  "wifi",
+  "bssid",
+  "ipaddr",
+  "localip",
+  "binddomain",
+  "host",
+  "address",
+  "room",
+  "area_name",
+  "areaname",
+  "segmentname",
+  "segment_name",
+  // room/zone/map names are user-set PII (FIX 3).
+  "zone_name",
+  "zonename",
+  "map_name",
+  "mapname",
+  // map binary / geometry (location-revealing)
+  "map_info",
+  "mapinfo",
+  "mapblob",
+  // free-text device names that may carry PII. NOTE: the bare fragment `name` is
+  // intentionally NOT listed — it would over-match the catalog's command `name`
+  // field (an enum-derived, non-sensitive label like `START`). ACCEPTED
+  // TRADE-OFF: a bare `{ name: "..." }` in an event argument is NOT scrubbed by
+  // key. This is mitigated in practice by (a) the value-sanitizer below
+  // (sanitizeStringValue, applied to EVERY string scalar — it catches OSS
+  // paths / URLs / tokens regardless of key), and (b) the specific
+  // customName/deviceName/nickName/zoneName/mapName fragments which cover the
+  // realistic PII-bearing name cases.
+  "customname",
+  "devicename",
+  "nickname"
+];
+var EXACT_SENSITIVE_KEYS = /* @__PURE__ */ new Set(["ip"]);
+function isSensitiveKey(key2) {
+  const lower = key2.toLowerCase();
+  if (EXACT_SENSITIVE_KEYS.has(lower)) {
+    return true;
+  }
+  return SENSITIVE_KEY_FRAGMENTS.some((frag) => lower.includes(frag));
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+var RISKY_VALUE_PATTERNS = [
+  /:\/\//,
+  // any URL scheme (https://, mqtts://, …) — signed URLs carry tokens
+  /ali_dreame\//i,
+  // OSS object path embedding uid/did
+  /[A-Za-z0-9_-]{32,}/,
+  // a long opaque token run (base64/hex secrets)
+  /\b(did|uid|token)\s*=/i,
+  // query-param secrets (?did=…&token=…)
+  /access/i
+  // accessKey / access-token / x-access-key style markers
+];
+function sanitizeStringValue(s) {
+  return RISKY_VALUE_PATTERNS.some((re) => re.test(s)) ? REDACTED : s;
+}
+function redact(value) {
+  if (Array.isArray(value)) {
+    return value.map((v) => redact(v));
+  }
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = isSensitiveKey(k) ? REDACTED : redact(v);
+    }
+    return out;
+  }
+  if (typeof value === "string") {
+    return sanitizeStringValue(value);
+  }
+  return value;
+}
+
+// src/diagnostics/dump-format.ts
+var import_zod3 = require("zod");
+var DumpScalarSchema = import_zod3.z.union([import_zod3.z.string(), import_zod3.z.number(), import_zod3.z.boolean()]);
+var PropertyObservationSchema = import_zod3.z.object({
+  values: import_zod3.z.array(DumpScalarSchema),
+  unmapped: import_zod3.z.array(DumpScalarSchema),
+  enum: import_zod3.z.string().optional(),
+  count: import_zod3.z.number(),
+  firstSeen: import_zod3.z.number(),
+  lastSeen: import_zod3.z.number()
+});
+var EventObservationSchema = import_zod3.z.object({
+  at: import_zod3.z.number(),
+  type: import_zod3.z.string(),
+  data: import_zod3.z.unknown().optional()
+});
+var RawFrameSchema = import_zod3.z.object({
+  at: import_zod3.z.number(),
+  source: import_zod3.z.string(),
+  payload: import_zod3.z.unknown()
+});
+var CommandSchema = import_zod3.z.object({
+  name: import_zod3.z.string(),
+  siid: import_zod3.z.number().optional(),
+  aiid: import_zod3.z.number().optional()
+});
+var SensorSchema = import_zod3.z.object({
+  model: import_zod3.z.string(),
+  channel: import_zod3.z.number().optional()
+});
+var DeviceDumpSchema = import_zod3.z.object({
+  schemaVersion: import_zod3.z.literal(1),
+  library: import_zod3.z.union([import_zod3.z.literal("nodedreame"), import_zod3.z.literal("nodewitt")]),
+  libraryVersion: import_zod3.z.string(),
+  device: import_zod3.z.object({
+    model: import_zod3.z.string(),
+    firmware: import_zod3.z.string().optional(),
+    region: import_zod3.z.string().optional(),
+    type: import_zod3.z.string().optional()
+  }),
+  observations: import_zod3.z.object({
+    properties: import_zod3.z.record(import_zod3.z.string(), PropertyObservationSchema),
+    events: import_zod3.z.array(EventObservationSchema),
+    rawFrames: import_zod3.z.array(RawFrameSchema).optional()
+  }),
+  catalog: import_zod3.z.object({
+    commands: import_zod3.z.array(CommandSchema).optional(),
+    capabilities: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown()).optional(),
+    sensors: import_zod3.z.array(SensorSchema).optional()
+  }),
+  meta: import_zod3.z.object({
+    startedAt: import_zod3.z.number(),
+    durationMs: import_zod3.z.number(),
+    generatedAt: import_zod3.z.number()
+  })
+});
+
+// src/diagnostics/dumper.ts
+function commandsForFamily(family) {
+  const commands = [];
+  if (family === "vacuum") {
+    for (const [name, ref] of Object.entries(VACUUM_ACTION)) {
+      commands.push({ name, siid: ref.siid, aiid: ref.aiid });
+    }
+  } else if (family === "mower") {
+    for (const [name, ref] of Object.entries(MOWER_ACTION)) {
+      commands.push({ name, siid: ref.siid, aiid: ref.aiid });
+    }
+  }
+  return commands;
+}
+function decoderFor(enumName, members) {
+  const lookup = enumLookup(members);
+  return { enumName, isMember: (raw) => lookup(raw) !== null };
+}
+function vacuumDecoders() {
+  return {
+    "2.1": decoderFor(
+      "MiotState",
+      Object.values(MiotState).filter((v) => typeof v === "number")
+    ),
+    "3.2": decoderFor(
+      "ChargingStatus",
+      Object.values(ChargingStatus).filter((v) => typeof v === "number")
+    ),
+    "4.4": decoderFor(
+      "SuctionLevel",
+      Object.values(SuctionLevel).filter((v) => typeof v === "number")
+    ),
+    "4.5": decoderFor(
+      "WaterVolume",
+      Object.values(WaterVolume).filter((v) => typeof v === "number")
+    ),
+    "2.6": decoderFor(
+      "CleaningMode",
+      Object.values(CleaningMode).filter((v) => typeof v === "number")
+    ),
+    "4.1": decoderFor(
+      "TaskStatus",
+      Object.values(TaskStatus).filter((v) => typeof v === "number")
+    )
+  };
+}
+function mowerDecoders() {
+  return {
+    "2.1": decoderFor(
+      "MowerStatus",
+      Object.values(MowerStatus).filter((v) => typeof v === "number")
+    ),
+    "3.2": decoderFor(
+      "MowerChargingStatus",
+      Object.values(MowerChargingStatus).filter(
+        (v) => typeof v === "number"
+      )
+    ),
+    "5.104": decoderFor(
+      "MowerTaskStatus",
+      Object.values(MowerTaskStatus).filter((v) => typeof v === "number")
+    ),
+    "2.2": decoderFor(
+      "MowerFault",
+      Object.values(MowerFault).filter((v) => typeof v === "number")
+    )
+  };
+}
+function toScalar(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  return null;
+}
+var PropertyAccumulator = class {
+  #decoders;
+  #entries = /* @__PURE__ */ new Map();
+  constructor(decoders = {}) {
+    this.#decoders = decoders;
+  }
+  record(siid, piid, rawValue, at) {
+    const key2 = `${siid}.${piid}`;
+    const scalar = toScalar(rawValue);
+    let entry = this.#entries.get(key2);
+    if (!entry) {
+      entry = { values: [], unmapped: [], count: 0, firstSeen: at, lastSeen: at };
+      this.#entries.set(key2, entry);
+    }
+    entry.count += 1;
+    entry.lastSeen = at;
+    if (scalar === null) {
+      return;
+    }
+    if (!entry.values.includes(scalar)) {
+      entry.values.push(scalar);
+    }
+    const decoder = this.#decoders[key2];
+    if (decoder && typeof scalar === "number" && !decoder.isMember(scalar)) {
+      if (!entry.unmapped.includes(scalar)) {
+        entry.unmapped.push(scalar);
+      }
+    }
+  }
+  snapshot() {
+    const out = {};
+    for (const [key2, e] of this.#entries) {
+      const decoder = this.#decoders[key2];
+      const base = {
+        values: [...e.values],
+        unmapped: [...e.unmapped],
+        count: e.count,
+        firstSeen: e.firstSeen,
+        lastSeen: e.lastSeen
+      };
+      out[key2] = decoder ? { ...base, enum: decoder.enumName } : base;
+    }
+    return out;
+  }
+};
+var DEFAULT_REFRESH_INTERVAL_MS = 3e4;
+var DEFAULT_MAX_RAW_FRAMES = 500;
+var Dumper = class {
+  #device;
+  #opts;
+  #acc;
+  #events = [];
+  #rawFrames = [];
+  #catalog;
+  #type;
+  #onProperty;
+  #onEvent;
+  #timer = null;
+  #startedAt = 0;
+  #started = false;
+  constructor(device, catalog, type, decoders, options = {}) {
+    this.#device = device;
+    this.#catalog = catalog;
+    this.#type = type;
+    this.#acc = new PropertyAccumulator(decoders);
+    this.#opts = {
+      captureRawFrames: options.captureRawFrames ?? false,
+      maxRawFrames: options.maxRawFrames ?? DEFAULT_MAX_RAW_FRAMES,
+      refreshIntervalMs: options.refreshIntervalMs ?? DEFAULT_REFRESH_INTERVAL_MS
+    };
+    this.#onProperty = (e) => {
+      this.#acc.record(e.siid, e.piid, e.value, Date.now());
+      this.#pushRaw("mqtt:property", e);
+    };
+    this.#onEvent = (e) => {
+      this.#events.push({
+        at: Date.now(),
+        type: `${e.siid}.${e.eiid}`,
+        data: { arguments: e.arguments }
+      });
+      this.#pushRaw("mqtt:event", e);
+    };
+  }
+  /** Attach to the live stream + arm the periodic shadow refresh. Idempotent. */
+  async start() {
+    if (this.#started) {
+      return;
+    }
+    this.#started = true;
+    this.#startedAt = Date.now();
+    this.#device.on("propertyChanged", this.#onProperty);
+    this.#device.on("event", this.#onEvent);
+    await this.#refresh();
+    if (this.#opts.refreshIntervalMs > 0 && this.#device.refreshFromCache) {
+      this.#timer = setInterval(() => void this.#refresh(), this.#opts.refreshIntervalMs);
+      this.#timer.unref?.();
+    }
+  }
+  /** Detach every listener + clear the timer. Idempotent. */
+  stop() {
+    if (!this.#started) {
+      return Promise.resolve();
+    }
+    this.#started = false;
+    if (this.#timer) {
+      clearInterval(this.#timer);
+      this.#timer = null;
+    }
+    this.#device.off("propertyChanged", this.#onProperty);
+    this.#device.off("event", this.#onEvent);
+    return Promise.resolve();
+  }
+  /** Build the anonymized, schema-valid dump. Works live or after {@link stop}. */
+  export() {
+    const now = Date.now();
+    const dump = {
+      schemaVersion: 1,
+      library: "nodedreame",
+      libraryVersion: LIBRARY_VERSION,
+      device: {
+        model: this.#device.model,
+        type: this.#type
+      },
+      observations: {
+        properties: this.#acc.snapshot(),
+        events: [...this.#events],
+        ...this.#opts.captureRawFrames ? { rawFrames: this.#redactFrames() } : {}
+      },
+      catalog: this.#catalog,
+      meta: {
+        startedAt: this.#startedAt,
+        durationMs: Math.max(0, now - this.#startedAt),
+        generatedAt: now
+      }
+    };
+    const anonymized = redact(dump);
+    return DeviceDumpSchema.parse(anonymized);
+  }
+  /** Deterministic pretty JSON of {@link export}. */
+  exportJson() {
+    return JSON.stringify(this.export(), null, 2);
+  }
+  async #refresh() {
+    if (this.#device.refreshFromCache) {
+      try {
+        await this.#device.refreshFromCache();
+      } catch {
+      }
+    }
+  }
+  #pushRaw(source, payload) {
+    if (!this.#opts.captureRawFrames) {
+      return;
+    }
+    this.#rawFrames.push({ at: Date.now(), source, payload });
+    if (this.#rawFrames.length > this.#opts.maxRawFrames) {
+      this.#rawFrames.shift();
+    }
+  }
+  #redactFrames() {
+    return this.#rawFrames.map((f) => ({ at: f.at, source: f.source, payload: redact(f.payload) }));
+  }
+};
+function familyOf(device) {
+  if (device instanceof VacuumDevice) {
+    return "vacuum";
+  }
+  if (device instanceof MowerDevice) {
+    return "mower";
+  }
+  if (!(device instanceof BaseDevice)) {
+    if (device.model.startsWith("dreame.vacuum.")) {
+      return "vacuum";
+    }
+    if (device.model.startsWith("dreame.mower.")) {
+      return "mower";
+    }
+  }
+  return "device";
+}
+function decodersFor(device) {
+  switch (familyOf(device)) {
+    case "vacuum":
+      return vacuumDecoders();
+    case "mower":
+      return mowerDecoders();
+    default:
+      return {};
+  }
+}
+function typeFor(device) {
+  return familyOf(device);
+}
+function catalogFor(device) {
+  return {
+    commands: commandsForFamily(familyOf(device)),
+    capabilities: { tokens: [...device.capabilities.list()] }
+  };
+}
+function createDumper(target, options) {
+  return new Dumper(
+    target,
+    catalogFor(target),
+    typeFor(target),
+    decodersFor(target),
+    options ?? {}
+  );
+}
+function createClientDumper(client, options) {
+  return client.devices.map((d) => createDumper(d, options));
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseDevice,
@@ -4178,6 +4636,8 @@ var Nodreame = class extends TypedEmitter {
   VacuumCapabilityResolver,
   VacuumDevice,
   WaterVolume,
+  createClientDumper,
+  createDumper,
   getMowerCapabilities,
   getVacuumCapabilities,
   renderMowerSvg,