homebridge-roborock-vacuum 1.4.6 → 1.4.7

package/CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+- Install: `npm ci`
+- Build: `npm run build` (runs `rimraf ./dist && tsc`; only `src/` is compiled to `dist/`)
+- Lint: `npm run lint` (Prettier check) / `npm run lint:fix`
+- Test: `npm test` (Jest)
+- Run a single test file: `npm test -- path/to/file.test.ts`
+- Run by name: `npm test -- -t "should do something"`
+- File + name: `npm test -- path/to/file.test.ts -t "should do something"`
+- Coverage: `npm test -- --coverage`
+- Debug flaky/async: add `--runInBand`
+
+CI parity sequence: `npm ci` → `npm run lint` → `npm run build` → `npm test -- --coverage`.
+
+Note: there are currently no committed Jest specs under `src/`. `roborockLib/test.js` is integration-style, not a Jest spec. New tests should be `*.test.ts` colocated in `src/`.
+
+## Architecture
+
+This is a Homebridge dynamic platform plugin that bridges Roborock vacuums to HomeKit. It has three source roots with very different concerns:
+
+- **`src/`** (TypeScript, strict mode, `module: commonjs`, `target: ES2018`) — the Homebridge plugin surface. Compiled to `dist/`; `dist/index.js` is the published entry point.
+  - `src/index.ts` registers the platform with Homebridge via `PLATFORM_NAME` from `settings.ts`.
+  - `src/platform.ts` is the `DynamicPlatformPlugin`. It restores cached accessories, then on `APIEvent.DID_FINISH_LAUNCHING` discovers devices via the Roborock API and registers/unregisters `PlatformAccessory`s. It also installs a process-wide filter for Node's DEP0040 deprecation warning emitted by an upstream dep — keep that filter in place when editing.
+  - `src/vacuum_accessory.ts` wires HomeKit Services/Characteristics to vacuum state and scene-switch behavior. Characteristic handlers must stay lightweight and resilient to null state.
+  - `src/crypto.ts` handles Roborock token encryption/decryption and key files. Returns safe defaults on decryption failure rather than throwing — preserve that behavior.
+  - `src/types.ts`, `src/settings.ts`, `src/logger.ts` — config shape, plugin/platform name constants, and the platform logger wrapper.
+  - `src/ui/index.ts` — TypeScript shared by the config UI; distinct from the `homebridge-ui/` runtime assets below.
+
+- **`roborockLib/`** (legacy JavaScript, **not** part of `tsc` compilation) — Roborock cloud/local protocol implementation, loaded from `src/platform.ts` via `require("../roborockLib/roborockAPI")`. Subdirectories cover MQTT transport, local connector, message queueing, auth, map parsing (`RRMapParser.js`), per-model feature flags (`deviceFeatures.js`), and packaging helpers. Treat changes here as risky — they impact both cloud and local device communication paths.
+
+- **`homebridge-ui/`** — Homebridge config UI: `server.js` (Express server using `@homebridge/plugin-ui-utils`) plus `public/` static assets. This is independent of `src/` compilation.
+
+The `src/` ↔ `roborockLib/` boundary is the main complexity: TypeScript is strict but `roborockAPI` is consumed via `require` and typed as `any` on the platform. When threading new fields through, either widen the surface in `src/types.ts` or keep narrow `unknown` + narrowing at the boundary.
+
+## OpenSpec workflow
+
+This repo uses OpenSpec (`openspec/`) for change proposals — see `openspec/AGENTS.md` and `openspec/project.md`. For non-trivial behavior changes, new capabilities, breaking changes, or architecture shifts, create a change proposal under `openspec/changes/<change-id>/` before coding rather than going straight to implementation.
+
+## Conventions worth knowing
+
+- Prettier: `tabWidth: 2`, `semi: true`, `trailingComma: "es5"`. Ignored: `coverage`, `dist`, `node_modules`, `__snapshots__`.
+- TS strict is on, but `noImplicitAny: false` for legacy interop. Don't introduce broad new `any` in TS code; prefer `unknown` + narrowing.
+- Existing snake_case filenames (e.g. `vacuum_accessory.ts`) are intentional — preserve them.
+- Constants like `PLUGIN_NAME` / `PLATFORM_NAME` are `UPPER_SNAKE_CASE` and load-bearing for Homebridge accessory caching — UUID generation must stay deterministic.
+- `config.schema.json` is the user-visible config contract; keep it aligned with `src/types.ts` and README when adding options.
+- `AGENTS.md` carries overlapping command/architecture guidance for other agentic tools; keep it in sync when changing the equivalent sections here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-roborock-vacuum",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "Roborock Vacuum Cleaner - plugin for Homebridge.",
   "license": "MIT",
   "keywords": [

package/roborockLib/roborockAPI.js

@@ -455,6 +455,9 @@ class Roborock {
           this.devices = this.devices.filter(
             (device) => !ignoredSet.has(device.sn)
           );
+          this.receivedDevices = (homedataResult.receivedDevices || []).filter(
+            (device) => !ignoredSet.has(device.sn)
+          );
 
           const allManagedDevices = (homedataResult.devices || []).concat(
             homedataResult.receivedDevices || []
@@ -1008,11 +1011,21 @@ class Roborock {
   }
 
   getProductAttribute(duid, attribute) {
-    const products = this.products;
-    const productID = this.devices.find(
-      (device) => device.duid == duid
-    ).productId;
-    const product = products.find((product) => product.id == productID);
+    // Owned devices live in this.devices; shared devices in this.receivedDevices.
+    const device =
+      this.devices.find((device) => device.duid == duid) ||
+      (this.receivedDevices || []).find((device) => device.duid == duid);
+
+    if (!device) {
+      this.log.warn(
+        `getProductAttribute: no device found for duid ${duid}, returning null for "${attribute}".`
+      );
+      return null;
+    }
+
+    const product = (this.products || []).find(
+      (product) => product.id == device.productId
+    );
 
     return product ? product[attribute] : null;
   }