@homebridge-plugins/homebridge-eufy-security 4.4.5-beta.0 → 4.4.5-beta.2

package/.claude/skills/new-device-support/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: new-device-support
+description: Full workflow to add support for a new Eufy Security device type across eufy-security-client and homebridge-eufy-security. Covers exploration, implementation, build verification, and git/PR creation.
+---
+
+# Add New Eufy Security Device Support
+
+You are adding support for a new device type to the eufy-security ecosystem. The user will provide a GitHub issue URL or device details (model name, model number like T86P2, device type number like 111). They may also provide raw device properties JSON.
+
+Use `$ARGUMENTS` for the issue URL or device details.
+
+## Phase 1 — Gather Information
+
+1. **Fetch the GitHub issue** (if URL provided) to extract: device name, model number (e.g. T86P2), device type number, raw properties JSON, firmware version, and any reference PRs.
+2. **Run the property mapping script**: Save the raw properties JSON to a temp file and run:
+   ```bash
+   node homebridge-eufy-security/.claude/skills/new-device-support/map-properties.mjs /tmp/<device>-raw-props.json
+   ```
+   This maps each raw `param_type` to its `CommandType`/`ParamType` enum name, matching property constants, and which existing device types use them. It also outputs a suggested DeviceProperties block. Use this output to identify the closest existing device and plan the property mapping.
+3. **Ask the user** two questions:
+   - Image naming convention (check if images already exist or need renaming)
+   - Enum name for the DeviceType (e.g. `CAMERA_4G_S330`)
+
+## Phase 2 — Plan (use EnterPlanMode)
+
+Create a detailed plan covering all files that need changes. The plan must be based on the actual raw device properties — never guess which properties a device supports.
+
+### Files to modify in eufy-security-client
+
+#### `src/http/types.ts` — 6 locations:
+
+1. **DeviceType enum**: Add `ENUM_NAME = <number>, //<model>` in numeric order
+2. **GenericTypeProperty states**: Add `<number>: "<Display Name> (<Model>)"` in numeric order
+3. **DeviceProperties**: Add `[DeviceType.ENUM_NAME]` block. Always starts with `...GenericDeviceProperties`. Map each raw param_type to its corresponding `PropertyName.*` property constant. Base on the closest existing device but only include properties that match the raw data.
+4. **StationProperties**: Add `[DeviceType.ENUM_NAME]` block if device can act as its own station (solo cameras, integrated devices). Use `...BaseStationProperties` plus station-specific properties.
+5. **DeviceCommands**: Add `[DeviceType.ENUM_NAME]` array. Commands depend on device capabilities (livestream, talkback, pan/tilt, download, snooze, preset positions, calibrate, alarm).
+6. **StationCommands**: Add `[DeviceType.ENUM_NAME]` array if device has station properties. Typically `[CommandName.StationReboot, CommandName.StationTriggerAlarmSound]`.
+
+#### `src/http/device.ts` — Classification methods:
+
+Add the new device type to all applicable static classification methods. Common ones:
+- `isCamera()` — if it's a camera/doorbell/floodlight
+- `hasBattery()` — if battery-powered
+- `isPanAndTiltCamera()` — if has PTZ
+- `isOutdoorPanAndTiltCamera()` — if outdoor PTZ (this feeds into `isSoloCameras()`)
+- `isFloodLight()`, `isIndoorCamera()`, `isDoorbell()`, etc. — as applicable
+
+Add a **new static type guard method** and matching **instance method**:
+```typescript
+static isNewDevice(type: number): boolean {
+  //<Model>
+  return DeviceType.ENUM_NAME == type;
+}
+
+public isNewDevice(): boolean {
+  return Device.isNewDevice(this.rawDevice.device_type);
+}
+```
+
+Update serial number checks if applicable:
+- `isIntegratedDeviceBySn()` — add `sn.startsWith("<model>")` if the device is integrated/standalone
+- `isSoloCameraBySn()` — add `sn.startsWith("<model>")` if it's a solo camera
+
+#### `src/http/station.ts`:
+
+- `isIntegratedDevice()` — if the device is standalone or can pair as its own station, it may already be covered by `isSoloCameras()`, `isFloodLight()`, etc. Only add explicit check if needed.
+
+#### `src/push/service.ts`:
+
+- If the device is 4G LTE or needs special push notification handling, expand the normalization block (~line 768) to include the new type guard.
+
+#### `docs/supported_devices.md`:
+
+Add an entry in the correct table section:
+```markdown
+| ![<Model> image](_media/<image_small>.png) | <Display Name> (<Model>) | :wrench: | Firmware: <version> |
+```
+Use `:wrench:` for initial support.
+
+### Files to modify in homebridge-eufy-security
+
+#### `homebridge-ui/public/utils/device-images.js`:
+
+Add a case in the `getImage()` switch:
+```javascript
+case <type_number>: return '<image_large>.png';
+```
+
+#### Image assets:
+
+- Rename or add images in `eufy-security-client/docs/_media/` (small + large)
+- Rename or add image in `homebridge-eufy-security/homebridge-ui/public/assets/devices/` (large only)
+
+## Phase 3 — Implement
+
+Execute the plan. Key implementation notes:
+
+- **Property mapping**: Use the output from `map-properties.mjs` (Phase 1) as the primary guide. When multiple property constants match the same `param_type` (e.g. `DeviceWatermarkProperty` vs `DeviceWatermarkSoloWiredDoorbellProperty`), pick the variant used by the closest existing device. Check the "Used by DeviceTypes" column in the script output.
+- **Insert in order**: When adding to enums, switch statements, or `if` chains, maintain numeric ordering by device type number.
+- **Audio recording property**: Different device families use different audio recording property constants (e.g. `DeviceAudioRecordingProperty`, `DeviceAudioRecordingStarlight4gLTEProperty`). Match the closest existing device.
+- **No Co-Authored-By**: Do not add co-author lines to commits.
+
+## Phase 4 — Build & Lint Verification
+
+Run these in parallel:
+```bash
+cd eufy-security-client && npm run build
+cd homebridge-eufy-security && npm run build
+```
+
+Then verify lint:
+```bash
+cd eufy-security-client && npm run lint
+cd homebridge-eufy-security && npm run lint
+```
+
+Note: eufy-security-client lint may fail due to a pre-existing `jiti` library issue unrelated to our changes. The TypeScript build succeeding is sufficient validation.
+
+## Phase 5 — Git & PR
+
+### eufy-security-client
+
+1. Discard any unrelated changes (e.g. `package-lock.json`)
+2. Sync develop with upstream: `git fetch upstream && git checkout develop && git merge upstream/develop`
+3. Create branch: `git checkout -b feat/<device-slug>`
+4. Stage only relevant files (images (should match the `<device-slug>`), `src/http/types.ts`, `src/http/device.ts`, `src/push/service.ts`, `docs/supported_devices.md`)
+5. Commit: `git commit -m "feat: add <Device Name> (<Model>, type <number>) support"`
+6. Push: `git push origin feat/<device-slug>`
+7. Create cross-fork PR:
+   ```bash
+   gh pr create --repo bropat/eufy-security-client --base develop \
+     --head lenoxys:feat/<device-slug> \
+     --title "feat: add <Device Name> (<Model>, type <number>) support" \
+     --body-file /tmp/pr-body-<branch>.md
+   ```
+
+### homebridge-eufy-security
+
+1. Branch from the current beta branch (check with `git branch`): `git checkout -b feat/<device-slug>`
+2. Stage: `homebridge-ui/public/utils/device-images.js` + any added image
+3. Commit: `git commit -m "feat: add <Device Name> (<Model>, type <number>) device image mapping"`
+4. Push: `git push origin feat/<device-slug>`
+5. Create PR:
+   ```bash
+   gh pr create --repo homebridge-plugins/homebridge-eufy-security \
+     --base <beta-branch> \
+     --title "feat: add <Device Name> (<Model>, type <number>) device image" \
+     --body-file /tmp/pr-body-<branch>.md
+   ```
+
+### PR body format
+
+Write PR bodies to `/tmp/pr-body-<branch>.md` files. Include:
+- `## Summary` — bullet points describing the changes
+- Cross-references: `Closes homebridge-plugins/homebridge-eufy-security#<issue>` in the client PR, `Closes #<issue>` in the plugin PR
+- `Depends on bropat/eufy-security-client#<pr>` in the plugin PR
+- `## Test plan` — checklist of verification steps
+
+### Link the issue
+
+After both PRs are created, update both PR bodies so they reference the issue with closing keywords.

package/.claude/skills/new-device-support/map-properties.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+/**
+ * map-properties.mjs
+ *
+ * Maps raw device param_type numbers from a device properties JSON dump
+ * to the corresponding property constants in eufy-security-client.
+ *
+ * Usage:
+ *   node map-properties.mjs <raw-properties.json>
+ *   cat raw.json | node map-properties.mjs
+ *
+ * The input JSON should be the rawProperties object from a device dump,
+ * e.g. { "1101": { "value": 100 }, "1013": { "value": 1 }, ... }
+ * or an array of { "param_type": 1101, "param_value": "..." } objects.
+ *
+ * Output: a table mapping each param_type to its CommandType/ParamType enum name
+ * and all property constants that use that key.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Paths relative to this script's location
+// eufy-security-client is a sibling repo at the same level as homebridge-eufy-security
+const CLIENT_ROOT = join(__dirname, "..", "..", "..", "..", "eufy-security-client");
+const TYPES_HTTP = join(CLIENT_ROOT, "src", "http", "types.ts");
+const TYPES_P2P = join(CLIENT_ROOT, "src", "p2p", "types.ts");
+
+// ── Step 1: Parse enum values from source ──────────────────────────────────
+
+function parseEnum(source, enumName) {
+  const map = new Map(); // number → enum member name
+  const re = new RegExp(`enum\\s+${enumName}\\s*\\{([\\s\\S]*?)\\}`, "m");
+  const match = source.match(re);
+  if (!match) return map;
+
+  const body = match[1];
+  for (const line of body.split("\n")) {
+    const m = line.match(/^\s*(\w+)\s*=\s*(\d+)/);
+    if (m) {
+      map.set(Number(m[2]), `${enumName}.${m[1]}`);
+    }
+  }
+  return map;
+}
+
+const httpSource = readFileSync(TYPES_HTTP, "utf-8");
+const p2pSource = readFileSync(TYPES_P2P, "utf-8");
+
+const paramTypeMap = parseEnum(httpSource, "ParamType");
+const commandTypeMap = parseEnum(p2pSource, "CommandType");
+const trackerCommandTypeMap = parseEnum(p2pSource, "TrackerCommandType");
+
+// Merge all enum maps (CommandType takes precedence as it's most commonly used)
+const allEnums = new Map();
+for (const [k, v] of paramTypeMap) allEnums.set(k, v);
+for (const [k, v] of trackerCommandTypeMap) allEnums.set(k, v);
+for (const [k, v] of commandTypeMap) allEnums.set(k, v);
+
+// ── Step 2: Parse property constants and their keys ────────────────────────
+
+// Match property constant definitions and extract their key field
+// Handles both direct keys and spread patterns
+function parsePropertyConstants(source) {
+  const props = []; // { constName, key, keyRaw, propertyName }
+
+  // Find each "export const XxxProperty" block
+  const constRegex = /export\s+const\s+(\w+Property)\s*:\s*\w+\s*=\s*\{([\s\S]*?)\};/g;
+  let m;
+  while ((m = constRegex.exec(source)) !== null) {
+    const constName = m[1];
+    const body = m[2];
+
+    // Extract key field
+    let key = null;
+    let keyRaw = null;
+    const keyMatch = body.match(/key:\s*(.+?)(?:,|\n)/);
+    if (keyMatch) {
+      keyRaw = keyMatch[1].trim();
+      // Resolve to numeric if it's an enum reference
+      if (keyRaw.startsWith('"') || keyRaw.startsWith("'")) {
+        key = keyRaw.replace(/['"]/g, ""); // string key
+      } else {
+        // It's an enum reference like CommandType.CMD_GET_BATTERY
+        const parts = keyRaw.split(".");
+        if (parts.length === 2) {
+          const enumName = parts[0];
+          let enumMap;
+          if (enumName === "CommandType") enumMap = commandTypeMap;
+          else if (enumName === "ParamType") enumMap = paramTypeMap;
+          else if (enumName === "TrackerCommandType") enumMap = trackerCommandTypeMap;
+
+          if (enumMap) {
+            for (const [num, fullName] of enumMap) {
+              if (fullName === keyRaw) {
+                key = num;
+                break;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Extract PropertyName
+    let propertyName = null;
+    const nameMatch = body.match(/name:\s*(PropertyName\.\w+)/);
+    if (nameMatch) {
+      propertyName = nameMatch[1];
+    }
+
+    // Handle spread: ...SomeOtherProperty (inherits key if not overridden)
+    let spreadFrom = null;
+    const spreadMatch = body.match(/\.\.\.(\w+Property)/);
+    if (spreadMatch) {
+      spreadFrom = spreadMatch[1];
+    }
+
+    props.push({ constName, key, keyRaw, propertyName, spreadFrom });
+  }
+
+  // Resolve spreads: if a property has no key but spreads from another, inherit
+  const byName = new Map(props.map((p) => [p.constName, p]));
+  for (const prop of props) {
+    if (prop.key === null && prop.spreadFrom) {
+      const parent = byName.get(prop.spreadFrom);
+      if (parent) {
+        prop.key = parent.key;
+        if (!prop.keyRaw) prop.keyRaw = `(spread from ${prop.spreadFrom}) ${parent.keyRaw}`;
+        if (!prop.propertyName) prop.propertyName = parent.propertyName;
+      }
+    }
+  }
+
+  return props;
+}
+
+const allProps = parsePropertyConstants(httpSource);
+
+// Build lookup: numeric key → list of property constants
+const keyToProps = new Map(); // key (number|string) → [{ constName, propertyName }]
+for (const p of allProps) {
+  if (p.key === null) continue;
+  const k = p.key;
+  if (!keyToProps.has(k)) keyToProps.set(k, []);
+  keyToProps.get(k).push({ constName: p.constName, propertyName: p.propertyName });
+}
+
+// ── Step 3: Parse DeviceProperties blocks to see which constants are used ──
+
+function parseDevicePropertiesUsage(source) {
+  // Find all [DeviceType.XXX]: { ... } blocks inside DeviceProperties
+  const usage = new Map(); // constName → Set of DeviceType names that use it
+  const dpRegex = /\[DeviceType\.(\w+)\]\s*:\s*\{([\s\S]*?)\}/g;
+  // Only search within the DeviceProperties section
+  const dpStart = source.indexOf("export const DeviceProperties");
+  const dpEnd = source.indexOf("export const StationProperties");
+  if (dpStart === -1) return usage;
+
+  const dpSection = source.slice(dpStart, dpEnd === -1 ? undefined : dpEnd);
+  let m;
+  while ((m = dpRegex.exec(dpSection)) !== null) {
+    const deviceType = m[1];
+    const body = m[2];
+    // Find all property constant references
+    const refRegex = /:\s*(\w+Property)/g;
+    let rm;
+    while ((rm = refRegex.exec(body)) !== null) {
+      const constName = rm[1];
+      if (!usage.has(constName)) usage.set(constName, new Set());
+      usage.get(constName).add(deviceType);
+    }
+  }
+  return usage;
+}
+
+const propUsage = parseDevicePropertiesUsage(httpSource);
+
+// ── Step 4: Read and parse input JSON ──────────────────────────────────────
+
+let inputData;
+const inputFile = process.argv[2];
+if (inputFile) {
+  inputData = readFileSync(inputFile, "utf-8");
+} else {
+  // Read from stdin
+  inputData = readFileSync("/dev/stdin", "utf-8");
+}
+
+let rawParamTypes; // Set of numeric param_type values
+try {
+  const parsed = JSON.parse(inputData);
+
+  if (Array.isArray(parsed)) {
+    // Array of { param_type: number, ... }
+    rawParamTypes = new Set(parsed.map((item) => Number(item.param_type)));
+  } else if (typeof parsed === "object") {
+    // Check if it's a full device dump with rawProperties nested
+    if (parsed.rawProperties && typeof parsed.rawProperties === "object") {
+      rawParamTypes = new Set(Object.keys(parsed.rawProperties).map(Number));
+    } else {
+      // Direct { "1101": ..., "1013": ... } format
+      rawParamTypes = new Set(Object.keys(parsed).map(Number));
+    }
+  }
+} catch {
+  console.error("Error: Could not parse input JSON. Provide either:");
+  console.error('  - A raw properties object: { "1101": {...}, "1013": {...}, ... }');
+  console.error('  - An array: [{ "param_type": 1101, ... }, ...]');
+  console.error("  - A device dump with rawProperties key");
+  process.exit(1);
+}
+
+// Filter out NaN (from string keys in the input)
+rawParamTypes = new Set([...rawParamTypes].filter((n) => !isNaN(n)));
+
+// ── Step 5: Output results ─────────────────────────────────────────────────
+
+const COL1 = 12; // param_type
+const COL2 = 48; // enum name
+const COL3 = 50; // property constants
+// COL4 reserved for future use
+
+const header = [
+  "param_type".padEnd(COL1),
+  "Enum Name".padEnd(COL2),
+  "Property Constant(s)".padEnd(COL3),
+  "Used by DeviceTypes",
+].join(" | ");
+
+console.log("=".repeat(header.length));
+console.log("Device Raw Properties → Property Constants Mapping");
+console.log(`Total raw param_types: ${rawParamTypes.size}`);
+console.log("=".repeat(header.length));
+console.log();
+console.log(header);
+console.log("-".repeat(header.length));
+
+const matched = [];
+const unmatched = [];
+
+for (const paramType of [...rawParamTypes].sort((a, b) => a - b)) {
+  const enumName = allEnums.get(paramType) || "???";
+  const props = keyToProps.get(paramType);
+
+  if (props && props.length > 0) {
+    const constNames = props.map((p) => p.constName);
+    const propertyNames = [...new Set(props.map((p) => p.propertyName).filter(Boolean))];
+    const usedBy = new Set();
+    for (const cn of constNames) {
+      const devices = propUsage.get(cn);
+      if (devices) devices.forEach((d) => usedBy.add(d));
+    }
+
+    matched.push({
+      paramType,
+      enumName,
+      constNames,
+      propertyNames,
+      usedBy: [...usedBy],
+    });
+
+    console.log(
+      [
+        String(paramType).padEnd(COL1),
+        enumName.padEnd(COL2),
+        constNames.join(", ").padEnd(COL3),
+        [...usedBy].slice(0, 5).join(", ") + (usedBy.size > 5 ? "..." : ""),
+      ].join(" | ")
+    );
+  } else {
+    unmatched.push({ paramType, enumName });
+    console.log(
+      [
+        String(paramType).padEnd(COL1),
+        enumName.padEnd(COL2),
+        "(no property constant found)".padEnd(COL3),
+        "",
+      ].join(" | ")
+    );
+  }
+}
+
+console.log();
+console.log("=".repeat(80));
+console.log(`MATCHED: ${matched.length} / ${rawParamTypes.size} param_types have property constants`);
+console.log(`UNMATCHED: ${unmatched.length} param_types have no known property constant`);
+console.log("=".repeat(80));
+
+if (unmatched.length > 0) {
+  console.log();
+  console.log("Unmatched param_types (may need new property constants or may be internal):");
+  for (const u of unmatched) {
+    console.log(`  ${u.paramType} → ${u.enumName}`);
+  }
+}
+
+// Output a suggested PropertyName list for use in DeviceProperties block
+console.log();
+console.log("=".repeat(80));
+console.log("SUGGESTED DeviceProperties block entries:");
+console.log("=".repeat(80));
+const seen = new Set();
+for (const m of matched) {
+  for (let i = 0; i < m.constNames.length; i++) {
+    const pn = m.propertyNames[0]; // Use first PropertyName
+    const cn = m.constNames[i];
+    if (pn && !seen.has(pn)) {
+      seen.add(pn);
+      console.log(`  [${pn}]: ${cn},`);
+    }
+  }
+}

package/dist/version.js

@@ -1,2 +1,2 @@
-export const LIB_VERSION = "4.4.5-beta.0";
+export const LIB_VERSION = "4.4.5-beta.2";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "displayName": "Homebridge Eufy Security",
   "name": "@homebridge-plugins/homebridge-eufy-security",
-  "version": "4.4.5-beta.0",
+  "version": "4.4.5-beta.2",
   "description": "Control Eufy Security from homebridge.",
   "type": "module",
   "license": "Apache-2.0",