@homebridge-plugins/homebridge-eufy-security 4.7.2 → 5.0.0-beta.0

package/i18n/runtime/en.json

@@ -0,0 +1,100 @@
+{
+  "log.action.allowBatteryCooling": "Allow the device battery to return to a safe temperature",
+  "log.action.checkNetwork": "Check network access and Eufy service availability",
+  "log.action.checkPhysicalArmingMode": "Check the physical security-system mode before retrying",
+  "log.action.checkPhysicalLight": "Check the physical smart-light state before retrying",
+  "log.action.checkPhysicalLock": "Check the physical lock state before retrying",
+  "log.action.checkCameraSnapshot": "Check that the camera is reachable and can produce an image, then open the camera again",
+  "log.action.waitCameraControl": "No action is needed; the control returns when the camera reports it again",
+  "log.action.checkCameraControl": "Check the camera in the Eufy app; this control is unavailable until it reports its state",
+  "log.action.retryCameraControl": "Try the control again; the camera did not confirm the change",
+  "log.action.enableCamera": "Turn the camera on in the Eufy app, then open live view again",
+  "log.action.openDashboard": "Review device representation in the Homebridge Eufy dashboard",
+  "log.action.reduceConcurrentMedia": "Open live view again; if it keeps happening, close a camera already open or raise the concurrent camera media limit in the plugin settings",
+  "log.action.reauthenticate": "Authenticate again in the Homebridge Eufy dashboard, then restart Homebridge",
+  "log.action.retryArming": "Retry the security-system control manually",
+  "log.action.retryLight": "Retry the smart-light control manually",
+  "log.action.retryLiveView": "Open live view again, and check network access between Homebridge and the camera",
+  "log.action.retryLock": "Retry the lock control manually",
+  "log.action.retryTalkback": "Close and reopen the camera, then try speaking again",
+  "log.action.reviewRuntime": "Review Homebridge Eufy health in the dashboard and restart Homebridge",
+  "log.action.stopOtherOwner": "Stop the other Homebridge Eufy owner before restarting Homebridge",
+  "log.action.selectSupportedArmingMode": "Select Stay, Away, or Disarm to leave the unsupported mode",
+  "log.action.waitBattery": "Wait for complete battery capability evidence",
+  "log.action.waitArming": "Wait for complete arming capability evidence",
+  "log.action.waitBatteryObservation": "Wait for a valid battery observation",
+  "log.action.waitCameraLive": "Wait for complete camera live media capability evidence",
+  "log.action.waitCameraSnapshot": "Wait for complete camera snapshot capability evidence",
+  "log.action.waitContact": "Wait for complete contact capability evidence",
+  "log.action.waitContactObservation": "Wait for a valid contact observation",
+  "log.action.waitLight": "Wait for complete smart-light capability evidence",
+  "log.action.waitLightObservation": "Wait for a valid smart-light observation",
+  "log.action.waitLock": "Wait for complete lock capability evidence",
+  "log.action.waitSiren": "Wait for complete siren capability evidence",
+  "log.action.waitSirenObservation": "Wait for a valid siren observation",
+  "log.action.waitTalkback": "Wait for complete camera talkback capability evidence",
+  "log.condition.active": "{summary}. {affected} {action}.",
+  "log.condition.affectedMany": "{count} accessories are affected.",
+  "log.condition.affectedNamed": "Affected: {names}.",
+  "log.condition.affectedOne": "1 accessory is affected.",
+  "log.condition.recovered": "Recovered: {summary}.",
+  "log.diagnosticFileFailed": "Diagnostic file logging failed; check storage permissions.",
+  "log.discardedSettings": "Some legacy settings were discarded. Review and acknowledge them in the Homebridge Eufy dashboard.",
+  "log.snapshotCacheInvalid": "An invalid retained camera image was removed",
+  "log.homekit.batteryCapabilityUnavailable": "Battery information is unavailable",
+  "log.homekit.armingCapabilityUnavailable": "Security-system information is unavailable",
+  "log.homekit.armingOperationFailed": "A security-system control failed",
+  "log.homekit.armingReconciliationExpired": "A security system did not confirm the requested mode",
+  "log.homekit.batteryTemperatureAlert": "A device reported a battery temperature alert",
+  "log.homekit.cameraLiveSessionFailed": "A live camera session ended without video",
+  "log.homekit.cameraSnapshotCapabilityUnavailable": "Camera snapshot acquisition is unavailable",
+  "log.homekit.cameraSnapshotUnavailable": "A camera image is unavailable, so a placeholder is shown",
+  "log.homekit.cameraStreamingCapabilityUnavailable": "Camera live media is unavailable",
+  "log.homekit.cameraTalkbackFailed": "Camera talkback stopped unexpectedly",
+  "log.homekit.cameraTalkbackUnavailable": "Camera talkback is unavailable",
+  "log.homekit.cameraControlsCapabilityUnavailable": "A camera control is unavailable",
+  "log.homekit.cameraControlOperationFailed": "A camera control did not take effect",
+  "log.homekit.invalidCameraControlObservation": "A camera control state could not be read",
+  "log.homekit.cameraRecordingRefused": "Recording is unavailable because the camera is turned off",
+  "log.homekit.cameraLiveSessionRefused": "Live view is unavailable because the camera is turned off",
+  "log.homekit.cameraMediaAtCapacity": "Live view was refused because this host had reached its configured limit of cameras streaming at once",
+  "log.homekit.contactCapabilityUnavailable": "Contact sensor information is unavailable",
+  "log.homekit.invalidBatteryObservation": "A battery observation is invalid",
+  "log.homekit.invalidContactObservation": "A contact sensor observation is invalid",
+  "log.homekit.invalidLightObservation": "A smart-light observation is invalid",
+  "log.homekit.invalidSirenObservation": "A siren observation is invalid",
+  "log.homekit.lightCapabilityUnavailable": "Smart-light information is unavailable",
+  "log.homekit.lightOperationFailed": "A smart-light control failed",
+  "log.homekit.lightReconciliationExpired": "A smart-light did not confirm the requested state",
+  "log.homekit.lockCapabilityUnavailable": "Lock control is unavailable",
+  "log.homekit.lockOperationFailed": "A lock control failed",
+  "log.homekit.lockReconciliationExpired": "A lock did not confirm the requested target",
+  "log.homekit.recognizedNotRepresented": "Some recognized devices cannot be represented in HomeKit",
+  "log.homekit.sirenCapabilityUnavailable": "Siren information is unavailable",
+  "log.homekit.unsupportedArmingMode": "A security system reported a mode Apple Home cannot represent",
+  "log.homekit.unusableLockAnnouncement": "A lock reported something this plugin cannot read, so its state is shown as unknown",
+  "log.notice.eventSubscriberFailed": "A device event consumer failed; review Homebridge Eufy health in the dashboard.",
+  "log.notice.ownershipAcquisitionFailed": "Account ownership could not be acquired; restart Homebridge before retrying.",
+  "log.notice.ownershipReleaseFailed": "Account ownership release failed; restart Homebridge before retrying.",
+  "log.notice.ownershipReleaseIncomplete": "Account ownership release remains incomplete; restart Homebridge before retrying.",
+  "log.notice.ownershipReleaseNotFinalized": "Account ownership release did not finish; restart Homebridge before retrying.",
+  "log.notice.registrySubscriberFailed": "A device registry consumer failed; review Homebridge Eufy health in the dashboard.",
+  "log.notice.shutdownFailed": "The Eufy runtime did not shut down cleanly; restart Homebridge before retrying.",
+  "log.notice.shutdownTimeout": "The Eufy runtime exceeded its shutdown deadline; Homebridge shutdown will continue.",
+  "log.notice.shutdownTimeoutWithDuration": "The Eufy runtime exceeded its shutdown deadline; Homebridge shutdown will continue. ({durationMs} ms)",
+  "log.notice.stateSubscriberFailed": "A runtime state consumer failed; review Homebridge Eufy health in the dashboard.",
+  "log.notice.statusPublicationFailed": "Runtime status could not be published; dashboard status may be stale.",
+  "log.notice.channelServeFailed": "Live runtime status could not be served to the plugin settings page; it will show the last published status instead.",
+  "log.notice.diagnosticsAuthorizationArmed": "Diagnostic evidence collection is now active in the plugin runtime.",
+  "log.notice.standDownNotRearmed": "Homebridge Eufy stood down for an authentication and could not take the account session back; restart Homebridge to bring it back.",
+  "log.notice.standDownAccountReplaced": "Homebridge Eufy stood down for an authentication that replaced the account; restart Homebridge to use the new account.",
+  "log.runtime.authenticationRequired": "Eufy authentication is required",
+  "log.runtime.failed": "The Eufy runtime failed",
+  "log.runtime.ownerConflict": "Another process owns the Eufy account session",
+  "log.runtime.state": "Homebridge Eufy runtime is {state}.",
+  "log.runtime.transportDegraded": "The Eufy connection is degraded",
+  "log.action.checkCameraRecording": "Check that HomeKit Secure Video is set up for this camera and that it reports motion",
+  "log.action.retryRecording": "No action is needed; recording is attempted again on the next trigger",
+  "log.homekit.cameraRecordingUnavailable": "HomeKit Secure Video recording is unavailable for this camera",
+  "log.homekit.cameraRecordingFailed": "A HomeKit Secure Video recording did not complete"
+}

package/package.json

@@ -1,13 +1,13 @@
 {
-  "displayName": "Homebridge Eufy Security",
+  "displayName": "Homebridge Eufy",
   "name": "@homebridge-plugins/homebridge-eufy-security",
-  "version": "4.7.2",
+  "version": "5.0.0-beta.0",
   "description": "Control Eufy Security from homebridge.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git://github.com/homebridge-plugins/homebridge-eufy-security.git"
+    "url": "git+https://github.com/homebridge-plugins/homebridge-eufy.git"
   },
   "funding": [
     {
@@ -16,21 +16,25 @@
     }
   ],
   "bugs": {
-    "url": "https://github.com/homebridge-plugins/homebridge-eufy-security/issues"
+    "url": "https://github.com/homebridge-plugins/homebridge-eufy/issues"
   },
   "engines": {
     "node": ">=24.5.0",
-    "homebridge": "^2.0.0"
+    "homebridge": "^2.4.0"
   },
   "main": "dist/index.js",
   "scripts": {
-    "lint": "prettier --check 'src/**/*.ts'",
-    "lint-fix": "prettier --write 'src/**/*.ts'",
-    "build": "npm run build-plugin && npm run postbuild",
+    "lint": "prettier --check 'src/**/*.ts' 'test/**/*.ts'",
+    "lint-fix": "prettier --write 'src/**/*.ts' 'test/**/*.ts'",
+    "build": "npm run build-plugin",
     "build-plugin": "rimraf ./dist && tsc",
-    "postbuild": "cp -r ./media ./dist/media",
-    "prebuild": "node --input-type=module -e \"import{readFileSync}from'fs';const p=JSON.parse(readFileSync('./package.json','utf8'));process.stdout.write('export const LIB_VERSION = '+JSON.stringify(p.version)+';\\n');\" > src/version.ts",
-    "prepublishOnly": "npm run lint && npm run build"
+    "guard:no-ecs": "bash scripts/guard-no-ecs.sh",
+    "qualify:release": "node scripts/qualify-release.mjs",
+    "docs:dev": "npm -C docs run dev",
+    "docs:build": "npm -C docs run build",
+    "test": "vitest run",
+    "verify": "npm run lint && npm run guard:no-ecs && npm run build && npm test",
+    "prepublishOnly": "npm run build && npm run qualify:release && npm run verify"
   },
   "keywords": [
     "homebridge-plugin",
@@ -42,21 +46,22 @@
     "camera"
   ],
   "dependencies": {
-    "@homebridge/plugin-ui-utils": "^2.2.5",
-    "eufy-security-client": "^4.1.1-1",
-    "ffmpeg-for-homebridge": "2.2.2",
-    "pick-port": "^2.2.1",
-    "rotating-file-stream": "^3.2.9",
-    "tar": "^7.5.20",
-    "tslog": "^4.10.2"
+    "@homebridge/plugin-ui-utils": "^2.2.6",
+    "@mega-yfue/eufy-sdk": "0.1.0",
+    "ffmpeg-for-homebridge": "2.2.2"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
-    "homebridge": "^2.1.1",
-    "prettier": "^3.9.5",
+    "@homebridge/hap-nodejs": "2.2.2",
+    "@types/node": "^26.4.1",
+    "homebridge": "^2.4.0",
+    "prettier": "^3.9.6",
     "rimraf": "^6.1.3",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
   },
-  "homepage": "https://github.com/homebridge-plugins/homebridge-eufy-security/wiki",
-  "author": "homebridge-eufy-security"
+  "homepage": "https://homebridge-plugins.github.io/homebridge-eufy/",
+  "author": "homebridge-eufy",
+  "allowScripts": {
+    "ffmpeg-for-homebridge@2.2.2": true
+  }
 }

package/.claude/CLAUDE.md

@@ -1,175 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with the homebridge-eufy-security plugin.
-
-## Project Overview
-
-Homebridge plugin that exposes Eufy Security devices to Apple HomeKit. Published as `@homebridge-plugins/homebridge-eufy-security` under the `homebridge-plugins` GitHub organization.
-
-Depends on `eufy-security-client` (upstream: bropat/eufy-security-client) for cloud API, P2P, push notifications, and MQTT communication.
-
-For detailed functional requirements, device coverage, configuration options, and architecture boundaries, see `.claude/PRD.md`.
-
-## Build & Dev Commands
-
-```bash
-npm run build          # rimraf dist -> tsc -> copy media/ to dist/
-npm run build-plugin   # rimraf dist -> tsc (no media copy)
-npm run lint           # prettier --check 'src/**/*.ts'
-npm run lint-fix       # prettier --write 'src/**/*.ts'
-```
-
-- No test suite -- there are no unit or integration tests
-- Output: `dist/`
-- Formatting is enforced by Prettier (`.prettierrc.json`); `npm run lint` fails on any unformatted file -- run `npm run lint-fix` to auto-format
-- ESLint has been removed (typescript-eslint has no TypeScript 7 compatible release); Prettier is the only style gate
-- Run `npm run lint` and `npm run build` before pushing
-
-## Architecture
-
-Entry point `src/index.ts` registers `EufySecurityPlatform` with Homebridge. The platform class (`src/platform.ts`) is the core -- it initializes the `EufySecurity` client, discovers devices, and creates HomeKit accessories.
-
-**Accessory classes** in `src/accessories/` map Eufy device types to HomeKit services:
-- `BaseAccessory.ts` -- root base class (characteristic registration, service pruning)
-- `Device.ts` (`DeviceAccessory`) -- extends `BaseAccessory`; adds sensor/battery services, property helpers
-- `CameraAccessory` -- cameras, doorbells, floodlights (handles streaming delegates); extends `DeviceAccessory`
-- `StationAccessory` -- base stations (security system service for arm/disarm); extends `BaseAccessory` directly
-- `LockAccessory`, `EntrySensorAccessory`, `MotionSensorAccessory`, `SmartDropAccessory` -- extend `DeviceAccessory`
-- `AutoSyncStationAccessory` -- virtual accessory that syncs station guard mode with HomeKit
-
-**Streaming pipeline** in `src/controller/`:
-- `streamingDelegate.ts` -- HomeKit camera streaming (FFmpeg-based)
-- `recordingDelegate.ts` -- HomeKit Secure Video recording
-- `snapshotDelegate.ts` -- snapshot handling
-- `LocalLivestreamManager.ts` -- manages P2P livestream sessions
-
-**Utilities** in `src/utils/`: logging (`utils.ts`), FFmpeg wrapper (`ffmpeg.ts`), two-way audio (`Talkback.ts`), config schema (`configTypes.ts`), internal interfaces (`interfaces.ts`).
-
-**Constants** in `src/settings.ts`: HKSV segment lengths, snapshot cache ages, streaming bitrate headroom, IDR intervals -- reference this when tuning streaming or recording behaviour.
-
-**Plugin UI** in `homebridge-ui/`: `server.js` (plain JS, prettier-ignored) handles UI server logic and diagnostics generation. The UI and the plugin runtime (`src/`) are **separate processes** that share state through `accessories.json` on disk (written by `src/utils/accessoriesStore.ts`, read by `homebridge-ui/server.js`). Both independently import `eufy-security-client` types (`DeviceType`, `PropertyName`, `Device`, etc.) -- changes to the device/station record shape must be kept in sync between `accessoriesStore.ts` and `server.js`.
-
-### Key source files for device registration and triage
-
-- `src/platform.ts` (`register_device`) -- device registration logic; devices can stack multiple capabilities (independent `if` blocks, not `else if`)
-
-## Key Technical Details
-
-- ESM project (`"type": "module"`, `"module": "NodeNext"`) -- imports must use `.js` extensions (NodeNext resolution requires explicit extensions)
-- TypeScript strict mode, ES2022 target (`noImplicitAny: false` relaxes implicit-any checks)
-- Node.js >=24.5.0 required
-- Homebridge ^2.0.0 (1.x no longer supported)
-- Uses `ffmpeg-for-homebridge` for video transcoding
-- `src/version.ts` is auto-generated at prebuild time -- do not edit manually
-- `prepublishOnly` runs lint + build automatically before `npm publish`
-- For local development, `eufy-security-client` can be pointed to a local path (e.g. `"../eufy-security-client"`)
-
-## Git Workflow
-
-**IMPORTANT: Create the branch BEFORE editing any files.**
-
-```bash
-# Create dedicated branch from beta before making any changes
-git checkout beta-*.*.* && git pull origin beta-*.*.*
-git checkout -b [fix/feat/chore]/<short-description>
-
-# Stage and commit each change individually
-git add <file>
-git commit -m "fix: <concise description of what changed and why>"
-
-# Push and create PR
-git push -u origin fix/<short-description>
-gh pr create --base beta-*.*.* --title "<concise title>" --body-file /tmp/pr-body.md
-```
-
-- Branch from `beta-*.*.*`, not `master`
-- PR target: `beta-*.*.*`
-- Branch naming: `fix/`, `feat/`, `chore/` prefix
-
-### Commit message rules
-
-- Single line, no line breaks mid-sentence
-- Describe the **spirit** of the change, not the code diff
-- No Co-Authored-By
-
-### PR body
-
-- Write to `/tmp/pr-body-<branch>.md` using file creation -- **never** use heredoc (`cat << EOF`) in the terminal (quotes and special characters break it)
-- Describe the **spirit** of the change, not the code diff
-- Concise description of the problem and fix
-- PR body is **not** the release note -- keep it focused on the code change for reviewers
-- No Co-Authored-By
-
-### Release notes
-
-- Write to `/tmp/release-notes-<version>.md` using file creation
-- **Audience is end users** -- focus on what matters to them: new devices, behaviour changes, removed settings, required actions
-- **Concise, bullet-driven** -- no markdown tables, no verbose paragraphs. Short section intros (1-2 sentences max) followed by bullet lists
-- **No internal milestones** -- don't mention "first GA since X" or beta iteration counts
-- **Structure for a branch** (e.g., `4.4.x`), not a single version:
-  - Individual `## v4.4.x` entries at the top with version-specific changes
-  - A shared `## What's in 4.4.x` section below covering the full branch
-- **Required actions front and center** -- if users need to change config or upgrade Node.js, say so early and clearly
-- **Tone**: direct, no filler, no emojis
-
-### Issue comments
-
-- Use `gh issue comment <number> --repo homebridge-plugins/homebridge-eufy-security --body "<message>"`
-- Use first person ("I")
-- Thank the user by @mention
-- Be formal and concise
-- **Audience is end users** -- keep language simple, no internal jargon
-- Don't scope a fix to a specific device when it applies broadly
-- When a fix is merged, check the published beta version (`npm view @homebridge-plugins/homebridge-eufy-security dist-tags`) and mention it in the comment
-
-## Dependency Policy -- `eufy-security-client`
-
-**CRITICAL:**
-- **`beta-*.*.*` branches** -- use the `dev` dist-tag (`"eufy-security-client": "dev"`)
-- **`master` branch** -- **NEVER** use the `dev` dist-tag. Always use a pinned stable version (e.g. `"^3.7.2"`). Before merging to master, replace `"dev"` with the corresponding stable release version.
-
-When updating the `eufy-security-client` version in `package.json`:
-1. Check the upstream changelog and README at https://github.com/bropat/eufy-security-client/blob/master/README.md
-2. Identify breaking changes, new features, or device support changes
-3. Summarize the impact in the PR body
-4. If there are breaking changes, note any required code adjustments
-
-## Skills
-
-Skills in `.claude/skills/` provide structured workflows for common tasks:
-
-| Skill | Purpose |
-|---|---|
-| `planner` | Build a step-by-step action plan with guardrails before coding |
-| `developer` | Execute code changes following an approved plan or direct instructions |
-| `qa` | Verify build, lint, imports, architecture, and git hygiene before pushing |
-| `architect` | Quick codebase questions, mini-bug debugging, workflow improvement |
-| `support` | Triage GitHub issues using diagnostics archives and logs |
-| `new-device-support` | Full workflow to add a new Eufy device type across both repos |
-
-Typical flow: **planner** -> **developer** -> **qa**. Use **architect** for exploration and **support** for issue triage.
-
-## Diagnostic Triage
-
-For issue triage, use the `support` skill with an issue number (e.g. `/support 423`). For the full triage reference, see `.github/prompts/diag-triage.prompt.md`. For adding new device types, use the `new-device-support` skill. Key points:
-
-- Diagnostics archives are encrypted (RSA-4096 + AES-256-GCM); decrypt with `node scripts/decrypt-diagnostics.mjs <file>.tar.gz`
-- Always check archive completeness before analysis -- missing runtime logs means the plugin wasn't running
-- When diagnostics are incomplete or debug is disabled, ask the user to upgrade to the latest [beta](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Special-Version-(BETA---RC---HKSV)) and follow the [Basic Troubleshooting](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Basic-Troubleshooting) steps to enable Detailed Logging, reproduce the issue, and re-export diagnostics
-- Narrow down whether the issue is in `homebridge-eufy-security` (accessory registration, HomeKit mapping, config handling) or in `eufy-security-client` (device discovery, property events, P2P, push notifications)
-- If the environment indicates HOOBS: label `hoobs` + `wontfix` and close -- HOOBS is not supported
-
-### Label recommendations
-
-| Label | When to use |
-|---|---|
-| `depends on eufy-security-client` | Issue originates in bropat's eufy-security-client library |
-| `device-support` | New device type support request |
-| `debug log missing` | Diagnostics lack logs or debug mode was disabled |
-| `configuration issue` | Problem caused by user config |
-| `livestream` | Camera livestream, video feed, P2P, RTSP, streaming failures |
-| `question` | Further information is requested |
-| `resolved in beta` | Fix already in current beta |
-| `needs triage` | New issue awaiting initial analysis |
-| `duplicate` | Issue or PR already exists |
-| `hoobs` | HOOBS-specific -- label as `hoobs` + `wontfix` and close |

package/.claude/PRD.md

@@ -1,241 +0,0 @@
-# PRD -- homebridge-eufy-security
-
-Product Requirements Document for `@homebridge-plugins/homebridge-eufy-security`.
-
-## Purpose
-
-Expose Eufy Security devices to Apple HomeKit via Homebridge. Users control cameras, doorbells, locks, sensors, base stations, and delivery boxes from the Home app -- including live video, HomeKit Secure Video recording, arm/disarm, and two-way audio.
-
-## Target Users
-
-Homebridge users with Eufy Security hardware who want native HomeKit integration without Eufy's official HomeKit firmware (limited or unavailable for most devices).
-
-## System Requirements
-
-| Requirement | Value |
-|---|---|
-| Node.js | >=24.5.0 |
-| Homebridge | ^2.0.0 |
-| Eufy Account | Dedicated guest account (admin accounts blocked) |
-| FFmpeg | Bundled via `ffmpeg-for-homebridge` |
-
----
-
-## Functional Requirements
-
-### FR-1: Device Discovery & Registration
-
-- Connect to Eufy cloud via `eufy-security-client` (cloud API, P2P, push notifications, MQTT)
-- Discover stations and devices automatically on plugin startup
-- Batch device processing with 10-second debounce to avoid thrashing during sync
-- Hot-add/remove devices after initial discovery completes
-- Restore cached accessories across Homebridge restarts
-- Prune stale cached accessories when `cleanCache: true`
-- Devices can stack multiple capabilities (camera + motion sensor + doorbell) via independent registration blocks
-
-### FR-2: Camera Streaming
-
-#### FR-2.1: Live Streaming
-- P2P direct stream (default, low latency)
-- RTSP stream (opt-in per camera)
-- FFmpeg transcoding to H.264 + AAC-ELD with SRTP encryption
-- Hardware encoder detection: VideoToolbox (macOS), V4L2 (Raspberry Pi), VAAPI/QSV (Linux)
-- Fallback to libx264 software encoding
-- Configurable max resolution, bitrate, frame rate
-- Max concurrent streams per camera (default 2)
-- Configurable livestream duration (default 30s, max 86400s)
-- RTCP keep-alive monitoring with inactivity timeout
-
-#### FR-2.2: HomeKit Secure Video (HKSV)
-- Record motion/doorbell events as fMP4 fragments
-- 4-second segment length (HomeKit requirement)
-- 8-second timeshift buffer for pre-motion capture
-- Audio recording (AAC-ELD or AAC-LC per HomeKit config)
-- Snapshot capture during active recording
-- Max 3 segment errors before connection reset
-
-#### FR-2.3: Snapshots
-- Four handling modes: AlwaysFresh, Balanced, CloudOnly (default), Auto
-- Intelligent caching with configurable thresholds (fresh: 15s, balanced: 30s)
-- Placeholder images for offline/disabled/unavailable states
-- Cloud snapshot skip within 30s of livestream capture (prevents quality degradation)
-
-#### FR-2.4: Two-Way Audio (Talkback)
-- Bidirectional audio via duplex stream
-- Caches audio data until device is ready
-- 2-second silence auto-stop
-- Configurable channel count (mono default)
-
-### FR-3: Security System (Stations)
-
-- Map Eufy guard modes to HomeKit security states (Stay, Away, Night, Off)
-- Per-station guard mode mapping (configurable numeric mode values)
-- Manual alarm trigger with configurable duration and HomeKit mode filter
-- Alarm arm delay and alarm event handling via push notifications
-- Multi-station sync via virtual AutoSyncStationAccessory (opt-in)
-
-### FR-4: Locks
-
-- Lock/unlock control via HomeKit LockMechanism service
-- Lock jammed state detection via push notifications
-- Lock management service (auto-security timeout, admin-only access)
-
-### FR-5: Sensors
-
-#### FR-5.1: Motion Sensors
-- Standalone motion detection service
-- Camera-integrated motion with configurable timeout
-- Multi-event support: person, pet, vehicle, sound, crying, dog, stranger
-
-#### FR-5.2: Entry Sensors (Contact Sensors)
-- Door/window open/closed state
-
-### FR-6: Doorbells
-
-- ProgrammableSwitchEvent on ring
-- Optional motion-triggers-doorbell mode
-- Optional indoor chime control switch
-- Snapshot delay on doorbell ring (configurable)
-
-### FR-7: Floodlights
-
-- Lightbulb service for floodlight control
-- Combined camera + light capabilities
-
-### FR-8: Smart Drop (Package Boxes)
-
-- One-way open via LockMechanism
-- Package delivery detection via ContactSensor
-
-### FR-9: Per-Device Switches
-
-- Enable/disable device switch
-- Motion detection toggle switch
-- Light control switch (floodlights)
-- Indoor chime toggle switch
-- All switches individually configurable per camera
-
----
-
-## Configuration Requirements
-
-### CR-1: Global Configuration
-- Eufy credentials (username, password, device name)
-- Country code (ISO 3166-1 alpha-2)
-- Polling interval (default 10 minutes)
-- Global guard mode mapping (hkHome, hkAway, hkNight, hkOff)
-- Device/station ignore lists by serial number
-- Debug logging toggle (`enableDetailedLogging`)
-- Log file opt-out (`omitLogFiles`)
-- Cache cleanup toggle (`cleanCache`, default true)
-- Auto-sync station mode toggle
-- Embedded PKCS1 support toggle (Node.js <24.5 workaround)
-
-### CR-2: Per-Camera Configuration
-- Stream source: P2P or RTSP
-- Enable/disable camera streaming entirely
-- Snapshot handling method (AlwaysFresh, Balanced, CloudOnly, Auto)
-- Audio enable/disable
-- Talkback enable/disable with channel count
-- HKSV recording duration
-- Motion timeout
-- Per-switch visibility (enable, motion, light, indoor chime)
-- Full FFmpeg video config override (codec, resolution, bitrate, filters, encoder options, custom binary path)
-
-### CR-3: Per-Station Configuration
-- Guard mode mapping overrides (hkHome, hkAway, hkNight, hkOff)
-- Manual alarm trigger modes and duration
-
----
-
-## Plugin UI Requirements
-
-### UI-1: Device Discovery
-- Login flow with TFA and captcha support
-- Discovery progress reporting (authenticating, queuing, processing, done)
-- Skip button for unsupported device intel wait
-- Admin account detection and blocking
-
-### UI-2: Device Management
-- Display discovered stations and devices with type, capabilities, power status
-- Show unsupported devices separately
-- Detect running plugin via heartbeat (accessories.json `storedAt` < 90s old)
-- Load stored accessories from cache when plugin is not running
-
-### UI-3: Diagnostics
-- Generate encrypted diagnostics archive (RSA-4096 + AES-256-GCM)
-- Rate-limited to 60-second minimum between downloads
-- Archive includes: config (sanitized), all log files, accessories.json, system info
-- Decryptable via `node scripts/decrypt-diagnostics.mjs`
-
-### UI-4: Storage Management
-- Reset plugin storage (persistent.json, accessories.json)
-- Clean all storage option
-- System info endpoint (plugin version, Node.js version, host OS)
-
----
-
-## Non-Functional Requirements
-
-### NFR-1: Logging
-- Rotating file streams (daily rotation, max 3 archives, 200MB limit)
-- Styled console output (color-coded by level)
-- Debug mode adds file:line references and library-level logging
-- Separate log streams: plugin, library, UI server, UI library, FFmpeg (global + per-camera + snapshots)
-
-### NFR-2: Reliability
-- Connection retry (3 attempts, 30s backoff) on Eufy cloud failure
-- P2P stream retry with exponential backoff (2-10s, max 3 attempts, 15s timeout per attempt)
-- Multi-consumer stream sharing via reference counting (streaming, recording, snapshots share one P2P connection)
-- 5-second grace period before stopping shared P2P stream
-- Node.js MaxListeners raised to 30 for multi-camera setups
-- fMP4 box validation (max 50MB per box) during HKSV recording
-
-### NFR-3: Compatibility
-- ESM module (`"type": "module"`, `"module": "NodeNext"`)
-- TypeScript strict mode, ES2022 target
-- PKCS1 padding workaround for Node.js 20/22 (restored natively in Node.js 24.5+)
-- Hardware codec probing at startup with graceful software fallback
-
-### NFR-4: Security
-- Encrypted credential persistence (never logged)
-- Guest account enforcement (admin account usage blocked)
-- TFA/captcha graceful handling with shutdown and re-auth prompt
-- Diagnostics archives encrypted before export
-
----
-
-## Architecture Boundaries
-
-### homebridge-eufy-security (this plugin)
-- Accessory registration and HomeKit service mapping
-- FFmpeg transcoding pipeline
-- Configuration handling and validation
-- Plugin UI (device discovery, diagnostics, storage management)
-- accessories.json persistence for UI communication
-
-### eufy-security-client (upstream dependency)
-- Eufy cloud API authentication and communication
-- P2P connection establishment and stream management
-- Push notification and MQTT event handling
-- Device type classification and property management
-- Command execution (arm/disarm, lock/unlock, etc.)
-
-Issues must be triaged to the correct layer. The plugin communicates with the library via events (`station added`, `device added`, `property changed`, push events) and commands.
-
----
-
-## Device Type Coverage
-
-| Category | HomeKit Services |
-|---|---|
-| Cameras | CameraRTPStreamManagement, MotionSensor, optional Switches |
-| Doorbells | Doorbell + Camera services, ProgrammableSwitchEvent |
-| Floodlights | Camera + Lightbulb services |
-| Base Stations | SecuritySystem (arm/disarm), optional manual alarm Switch |
-| Smart Locks | LockMechanism, LockManagement |
-| Entry Sensors | ContactSensor |
-| Motion Sensors | MotionSensor |
-| Smart Drop | LockMechanism (open-only), ContactSensor (package detect) |
-| Video Locks | Camera + Lock services (LockWifiVideo) |
-| Auto-Sync Station | Virtual SecuritySystem syncing multiple stations |