@apocaliss92/nodedreame 1.2.0 → 1.3.0

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/support/version.ts
 var LIBRARY_NAME = "nodedreame";
+var LIBRARY_VERSION = "1.3.0";
 
 // src/transport/errors.ts
 var DreameError = class extends Error {
@@ -2769,11 +2770,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
@@ -3858,7 +3859,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) {
@@ -4082,6 +4083,429 @@ 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",
+  "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",
+  // 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). The specific custom-name
+  // fields below cover every PII-bearing case.
+  "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);
+}
+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;
+  }
+  return value;
+}
+
+// src/diagnostics/dump-format.ts
+import { z as z3 } from "zod";
+var DumpScalarSchema = z3.union([z3.string(), z3.number(), z3.boolean()]);
+var PropertyObservationSchema = z3.object({
+  values: z3.array(DumpScalarSchema),
+  unmapped: z3.array(DumpScalarSchema),
+  enum: z3.string().optional(),
+  count: z3.number(),
+  firstSeen: z3.number(),
+  lastSeen: z3.number()
+});
+var EventObservationSchema = z3.object({
+  at: z3.number(),
+  type: z3.string(),
+  data: z3.unknown().optional()
+});
+var RawFrameSchema = z3.object({
+  at: z3.number(),
+  source: z3.string(),
+  payload: z3.unknown()
+});
+var CommandSchema = z3.object({
+  name: z3.string(),
+  siid: z3.number().optional(),
+  aiid: z3.number().optional()
+});
+var SensorSchema = z3.object({
+  model: z3.string(),
+  channel: z3.number().optional()
+});
+var DeviceDumpSchema = z3.object({
+  schemaVersion: z3.literal(1),
+  library: z3.union([z3.literal("nodedreame"), z3.literal("nodewitt")]),
+  libraryVersion: z3.string(),
+  device: z3.object({
+    model: z3.string(),
+    firmware: z3.string().optional(),
+    region: z3.string().optional(),
+    type: z3.string().optional()
+  }),
+  observations: z3.object({
+    properties: z3.record(z3.string(), PropertyObservationSchema),
+    events: z3.array(EventObservationSchema),
+    rawFrames: z3.array(RawFrameSchema).optional()
+  }),
+  catalog: z3.object({
+    commands: z3.array(CommandSchema).optional(),
+    capabilities: z3.record(z3.string(), z3.unknown()).optional(),
+    sensors: z3.array(SensorSchema).optional()
+  }),
+  meta: z3.object({
+    startedAt: z3.number(),
+    durationMs: z3.number(),
+    generatedAt: z3.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));
+}
 export {
   BaseDevice,
   ChargingStatus,
@@ -4110,6 +4534,8 @@ export {
   VacuumCapabilityResolver,
   VacuumDevice,
   WaterVolume,
+  createClientDumper,
+  createDumper,
   getMowerCapabilities,
   getVacuumCapabilities,
   renderMowerSvg,