@homebridge-plugins/homebridge-eufy-security 4.6.0-beta.4 → 4.6.0-beta.41

package/.claude/skills/developer/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: developer
+description: Execute code changes following an approved plan or direct user instructions. Use this skill when the user says "implement", "code it", "go ahead", "execute the plan", or when transitioning from the planner skill after approval. Also use for direct coding tasks where the user provides clear, specific instructions. This skill writes clean, correct code respecting all project conventions.
+---
+
+# Developer
+
+You are a code execution agent for homebridge-eufy-security. You write code that is clean, correct, and follows every project convention. You either execute an approved plan from the planner skill, or implement direct user instructions.
+
+Follow all conventions in CLAUDE.md (ESM imports, lint, architecture patterns, code style, git workflow).
+
+## Before writing any code
+
+1. **Read first**: Read every file you intend to modify. Understand existing patterns before touching them.
+2. **Check the plan**: If a plan was approved, follow it exactly. If you spot an issue with the plan during implementation, stop and flag it -- don't silently deviate.
+3. **Branch check**: Verify you're on the correct branch per CLAUDE.md git workflow.
+
+## Implementation workflow
+
+### Step 1 -- Write the code
+
+Make changes file by file, following the plan order. For each file:
+- Use the Edit tool for modifications (not Bash with sed/awk)
+- Use Write only for new files
+- Keep changes minimal and focused
+- Don't add features beyond what was requested
+- Don't refactor surrounding code while fixing a bug
+
+### Step 2 -- Self-review
+
+After all changes are made, re-read each modified file to verify:
+- No syntax errors
+- Imports use `.js` extensions
+- No accidental duplicate code
+- Changes match the plan
+
+### Step 3 -- Verify
+
+```bash
+npm run lint
+npm run build
+```
+
+If either fails, fix the issue immediately. Do not commit code that doesn't lint or build.
+
+### Step 4 -- Commit
+
+Follow the git workflow from CLAUDE.md. Stage each logical change individually.
+
+## Chaining
+
+After committing, automatically invoke the **qa** skill to verify the changes before pushing. Do not wait for the user to ask -- QA is part of the development flow.
+
+## When things go wrong
+
+- **Lint failure**: Fix the warning. Don't disable the rule.
+- **Build failure**: Read the error. If it's a type error, trace it back. If it's an import error, check `.js` extensions.
+- **Plan doesn't work**: Stop. Explain what you found. Don't improvise a workaround without user approval.
+- **Unclear requirement**: Ask. Don't guess.

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Full workflow to add support for a new Eufy Security device type (cameras, locks, sensors, and other devices) across eufy-security-client and homebridge-eufy-security. Covers exploration, implementation, build verification, and git/PR creation.
 ---
 
 # Add New Eufy Security Device Support
@@ -11,13 +11,28 @@ 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:
+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. Note: users on recent eufy-security-client versions see a structured "unknown device" debug message that includes raw properties in a format directly usable with the mapping script.
+2. **Check for existing upstream work** — before starting, search for PRs that already add this device:
    ```bash
-   node homebridge-eufy-security/.claude/skills/new-device-support/map-properties.mjs /tmp/<device>-raw-props.json
+   gh pr list --repo bropat/eufy-security-client --state all --search "<model> OR <device-type-number>" --limit 10
    ```
-   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:
+   If a PR exists: review its diff to see what's already implemented, what's missing (e.g. missing GenericTypeProperty label, incomplete DeviceCommands), and whether it's merged, open, or stale. If merged, the device may only need homebridge-eufy-security side changes. If open but incomplete, coordinate with the PR author or build on their work. If the PR has review comments, check for flagged issues.
+3. **Pre-flight checks** — before proceeding, confirm you have:
+   - Device type number (required — cannot proceed without it)
+   - Raw device properties JSON (required for accurate property mapping — if missing, ask the user to enable debug logging and re-export diagnostics)
+   - Model number / display name (needed for enum naming and documentation)
+   - If the device type number is completely unknown (not in any existing code), investigate: check the model number prefix pattern, look at raw properties to infer capabilities (camera properties? lock properties? sensor properties?), and check Eufy's product pages for the model.
+4. **Run the pre-implementation audit**: Before writing any code, run the audit script to see what already exists:
+   ```bash
+   node homebridge-eufy-security/.claude/skills/new-device-support/check-device.mjs <type-number> [--pr-search <model>]
+   ```
+   This checks all 6 registration points in types.ts, classification methods in device.ts, device-images.js, finds the closest existing devices by property overlap, and searches upstream PRs. Use its output to understand the starting point.
+5. **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 --closest
+   ```
+   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. The `--closest` flag ranks existing devices by property overlap to identify the best base device.
+6. **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`)
 
@@ -25,12 +40,32 @@ Use `$ARGUMENTS` for the issue URL or device details.
 
 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.
 
+### Determine device category
+
+Before planning file changes, identify the device category — this determines which classification methods and accessory classes apply:
+
+- **Camera** (including doorbells, floodlights, indoor cameras, solo cameras, 4G cameras): uses `CameraAccessory` in the plugin. Classification methods: `isCamera()`, and optionally `isDoorbell()`, `isFloodLight()`, `isIndoorCamera()`, `isPanAndTiltCamera()`, `isOutdoorPanAndTiltCamera()`, `isSoloCameras()`, etc. Note: `isSoloCameras()` is a composite method that includes outdoor PTZ, wall light cams, and other standalone camera types.
+- **WallLightCam**: uses `CameraAccessory`. Classification: `isWallLightCam()`. This category is heavily referenced in `station.ts` (50+ references) for livestream, talkback, property handling, and command routing — expect substantial `station.ts` changes.
+- **GarageCamera**: uses `CameraAccessory`. Classification: `isGarageCamera()`. Has dedicated property variants (e.g. `DeviceWatermarkGarageCameraProperty`, `DeviceMotionDetectionSensitivityGarageCameraProperty`). Also has `isGarageCameraBySn()` for serial number matching.
+- **Lock** (BLE, WiFi, WiFi Video variants): uses `LockAccessory`. Classification methods: `isLock()`, `isLockWifi()`, `isLockBle()`, `isLockWifiVideo()`, etc. Locks have many specialized type guard methods (e.g. `isLockWifiT8531()`, `isLockWifiR10()`) — check existing patterns carefully. Locks may require changes in **three additional layers** beyond this skill's primary scope — flag these to the user:
+  - `src/mqtt/` — MQTT protocol for lock communication
+  - `src/p2p/session.ts` — P2P session initialization uses `Device.isLockWifi()` and `Device.isLockWifiNoFinger()` for lock sequence generation
+  - `src/http/station.ts` — lock-specific routing at station level
+- **Sensor** (entry sensor, motion sensor, PIR sensor): uses `EntrySensorAccessory` or `MotionSensorAccessory`. Classification: `isSensor()`, `isEntrySensor()`, `isMotionSensor()`. Note: `isSensor()` is static-only — no public instance method exists.
+- **SmartDrop**: uses `SmartDropAccessory`. Classification: `isSmartDrop()`. Also has `isSmartDropBySn()` for serial number matching.
+- **SmartSafe**: no HomeKit accessory currently. Classification: `isSmartSafe()`.
+- **Tracker/SmartTrack**: no HomeKit accessory currently. Classification: `isSmartTrack()`.
+- **Keypad**: no HomeKit accessory currently. Classification: `isKeyPad()`.
+- **WaterFreezeSensor**: no HomeKit accessory currently. Classification: check for `WATER_FREEZE_SENSOR_*` in DeviceType enum.
+- **Siren**: no HomeKit accessory currently. Classification: check for `SIREN_SENSOR_*` in DeviceType enum.
+- **New category**: if the device doesn't fit any existing category, a new accessory class is needed in `src/accessories/`, a new classification method, and a new `if` block in `register_device()`. Flag this to the user — it's a significantly larger task.
+
 ### 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
+2. **GenericTypeProperty `states` field**: Add `<number>: "<Display Name> (<Model>)"` inside the `states` object in numeric order. **WARNING**: This is one of the most commonly forgotten steps. Missing this label causes the device to display as a raw number in downstream UIs (see upstream PR #828 where 5 device types had missing labels).
 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).
@@ -38,14 +73,24 @@ Create a detailed plan covering all files that need changes. The plan must be ba
 
 #### `src/http/device.ts` — Classification methods:
 
-Add the new device type to all applicable static classification methods. Common ones:
+Add the new device type to all applicable static classification methods. There are two kinds:
+
+**Broad classification methods** (add device to these as applicable):
 - `isCamera()` — if it's a camera/doorbell/floodlight
-- `hasBattery()` — if battery-powered
+- `hasBattery()` — if battery-powered (critical — omitting this means no battery service in HomeKit)
 - `isPanAndTiltCamera()` — if has PTZ
-- `isOutdoorPanAndTiltCamera()` — if outdoor PTZ (this feeds into `isSoloCameras()`)
-- `isFloodLight()`, `isIndoorCamera()`, `isDoorbell()`, etc. — as applicable
+- `isOutdoorPanAndTiltCamera()` — if outdoor PTZ (included by `isSoloCameras()`)
+- `isSoloCameras()` — composite method aggregating solo/standalone camera types
+- `isFloodLight()`, `isIndoorCamera()`, `isDoorbell()`, `isWallLightCam()`, `isGarageCamera()` — as applicable
+- `isLock()`, `isLockWifi()`, `isLockBle()`, `isLockWifiNoFinger()` — if it's a lock variant
+- `isSensor()`, `isEntrySensor()`, `isMotionSensor()` — if it's a sensor
+- `isSmartDrop()`, `isSmartSafe()`, `isSmartTrack()`, `isKeyPad()` — as applicable
+
+Note: Not all broad methods have public instance counterparts (e.g. `isSensor()` is static-only). Don't create instance methods where none exist for the pattern.
 
-Add a **new static type guard method** and matching **instance method**:
+**`isSupported()` check**: After adding to `DeviceProperties` map, `Device.isSupported(type)` automatically returns `true` (it checks `DeviceProperties[type] !== undefined`). This is the foundation of device registration — if `DeviceProperties` entry is missing, the device is silently unsupported regardless of all other registrations.
+
+Add a **new dedicated type guard method** (static + instance pair):
 ```typescript
 static isNewDevice(type: number): boolean {
   //<Model>
@@ -57,9 +102,12 @@ public isNewDevice(): boolean {
 }
 ```
 
-Update serial number checks if applicable:
+Update serial number checks if applicable (all are static-only, no instance methods):
 - `isIntegratedDeviceBySn()` — add `sn.startsWith("<model>")` if the device is integrated/standalone
 - `isSoloCameraBySn()` — add `sn.startsWith("<model>")` if it's a solo camera
+- `isSmartDropBySn()` — add if it's a SmartDrop variant
+- `isGarageCameraBySn()` — add if it's a garage camera variant
+- `isFloodlightBySn()` — add if it's a floodlight variant
 
 #### `src/http/station.ts`:
 
@@ -67,7 +115,7 @@ Update serial number checks if applicable:
 
 #### `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.
+- 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`:
 
@@ -79,6 +127,10 @@ Use `:wrench:` for initial support.
 
 ### Files to modify in homebridge-eufy-security
 
+#### `src/platform.ts` — `register_device()`:
+
+Verify the new device type is handled by `register_device()`. This method uses independent `if` blocks (not `else if`) to map device types to accessory classes. If the device is a camera, it falls through to the camera path. If it's a lock, sensor, or SmartDrop, it hits those specific checks. If it's a new category that doesn't match any existing check, the device won't get an accessory — flag this to the user.
+
 #### `homebridge-ui/public/utils/device-images.js`:
 
 Add a case in the `getImage()` switch:
@@ -95,38 +147,48 @@ case <type_number>: return '<image_large>.png';
 
 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.
+- **Property mapping**: Use the output from `map-properties.mjs` (Phase 1) as the primary guide. Many property constants have large variant families (e.g. `DeviceMotionDetection*` has 40+ variants, `DeviceFloodlightLight*` has 12+, `DeviceVideoRecordingQuality*` has 11+). When multiple constants match the same `param_type`, pick the variant used by the closest existing device — check the "Used by DeviceTypes" column in the script output and the `--closest` flag results.
+- **Companion custom properties**: Some properties have required companions with `custom_*` keys that never appear in raw device data (they're populated at runtime). The script detects these and marks them with `⚠ companion`. Always include them — omitting a companion breaks functionality silently. Key pairs: `DeviceRTSPStream` → `DeviceRTSPStreamUrl`, `DeviceWifiRSSI` → `DeviceWifiSignalLevel`, `DeviceCellularRSSI` → `DeviceCellularSignalLevel`.
 - **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
+### Registration verification checklist
 
-Run these in parallel:
+After implementing all changes, run the post-implementation verification script:
 ```bash
-cd eufy-security-client && npm run build
-cd homebridge-eufy-security && npm run build
+node homebridge-eufy-security/.claude/skills/new-device-support/verify-device.mjs <ENUM_NAME>
 ```
+This automatically checks all required registration points and reports PASS/FAIL:
+
+1. `DeviceType` enum definition
+2. `GenericTypeProperty` states
+3. `DeviceProperties` map
+4. `DeviceCommands` map
+5. `StationProperties` map (if device acts as its own station — reported as WARN if missing)
+6. `StationCommands` map (if device has station properties — reported as WARN if missing)
+7. Dedicated type guard method (static + instance) in device.ts
+8. Broad classification methods (isCamera, isLock, etc.) in device.ts
+9. `docs/supported_devices.md` entry (reported as WARN if missing)
+10. `*BySn` serial number methods (reported as WARN if missing — not all devices need these)
+11. device-images.js case in homebridge-eufy-security
+
+The script exits with code 1 if any required checks fail. A device type that is defined in the enum but missing from DeviceProperties will silently fall back to GenericDeviceProperties with only ~3 basic properties (name, model, serial). This is the most common implementation error — see upstream issue #853 where LOCK_85V0 was added to the enum but never registered in the lookup maps.
 
-Then verify lint:
-```bash
-cd eufy-security-client && npm run lint
-cd homebridge-eufy-security && npm run lint
-```
+## Phase 4 — Build & Lint Verification
 
-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.
+Run build and lint for both repos. 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
+Follow CLAUDE.md Git Workflow for commit messages, branch naming, and PR body format. This skill creates **two PRs** across repos:
+
+### eufy-security-client (cross-fork)
 
-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:
+1. Discard unrelated changes (e.g. `package-lock.json`)
+2. Sync develop: `git fetch upstream && git checkout develop && git merge upstream/develop`
+3. Branch: `git checkout -b feat/<device-slug>`
+4. Stage only: images, `src/http/types.ts`, `src/http/device.ts`, `src/push/service.ts`, `docs/supported_devices.md`
+5. Cross-fork PR:
    ```bash
    gh pr create --repo bropat/eufy-security-client --base develop \
      --head lenoxys:feat/<device-slug> \
@@ -136,26 +198,15 @@ Note: eufy-security-client lint may fail due to a pre-existing `jiti` library is
 
 ### homebridge-eufy-security
 
-1. Branch from the current beta branch (check with `git branch`): `git checkout -b feat/<device-slug>`
+1. Branch from current beta: `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:
+3. PR to current beta branch:
    ```bash
-   gh pr create --repo homebridge-plugins/homebridge-eufy-security \
-     --base <beta-branch> \
-     --title "feat: add <Device Name> (<Model>, type <number>) device image" \
+   gh pr create --base beta-<current-version> \
+     --title "feat: add <Device Name> (<Model>) 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
+### Cross-referencing
 
-After both PRs are created, update both PR bodies so they reference the issue with closing keywords.
+After both PRs are created, update both bodies so they reference each other.