@7365admin1/core 3.42.3 → 3.44.0

package/docs/camera-integration-config.md

@@ -0,0 +1,191 @@
+# Camera integration — configuration reference
+
+How to switch each camera capability on, and who has to approve it.
+
+Everything here is **configuration**. Nothing in this document requires a code
+change, which is the point of the integration layer: the transports, the Dahua
+adapter and the capability descriptor are already built and tested, and each
+capability starts answering `supported` when the variables below are set.
+
+---
+
+## 1. What works with no configuration at all
+
+| Capability | Transport | Needs |
+|---|---|---|
+| `liveVideo` | `RELAY_PLAYER` | nothing — the camera record's `host` is the player-page URL, and a client renders it in a WebView |
+| `digitalZoom` | `RELAY_PLAYER` / `RTSP_FRAME` | nothing — it is client-side, on whichever picture arrived |
+
+## 2. What needs the RTSP recorder (already set on staging)
+
+| Capability | Transport | Needs |
+|---|---|---|
+| `stillFrame` | `RTSP_FRAME` | `ffmpeg` on the API host, and `CAMERA_RTSP_DEVICES` |
+
+```
+CAMERA_RTSP_DEVICES={"<relay-authority>":{"host":"<recorder-host>","port":554,"username":"<user>","password":"<password>"}}
+CAMERA_FFMPEG_PATH=/usr/bin/ffmpeg          # optional; "ffmpeg" on PATH by default
+```
+
+Keyed by **relay authority** — the host part of `site.cameras.host` — because
+that is the only stable identifier a camera record carries. The numeric last
+path segment of the stored host is the **channel** on that recorder.
+
+A camera whose relay has no entry here reports
+`stillFrame: unsupported / no-recorder-configured`, which is a deployment fix. A
+camera whose address carries no channel reports `no-channel-in-address`, which is
+a data fix. The two are deliberately different answers.
+
+### 2.1 The same entry is what makes camera SETUP self-service
+
+`CAMERA_RTSP_DEVICES` is read in both directions now.
+
+- **Viewing** asks "given this relay, which recorder?" — the direction the stored
+  records need.
+- **Setting a camera up** asks the opposite: the person at the form has the
+  recorder in front of them and no idea what a relay is, so the server looks the
+  entry up by recorder host and builds `https://<relay-authority>/<channel>`
+  itself. There is deliberately no second map.
+
+So **one entry per recorder unlocks every channel on it** for the site's own
+staff. A recorder with no entry is refused at the form with *"This recorder is
+not connected to the video service yet…"* — the same deployment fix as
+`no-recorder-configured`, said to a property manager instead of to a lead.
+
+The **"Test this camera"** button in the form reads the same entry. It is
+rationed before it can reach the device — one test per camera per 15 s, and 4
+per recorder per 5 minutes — and it checks the shared authentication budget
+first, so pressing it cannot walk a recorder into its own
+3-failures-in-30-seconds lockout.
+
+## 3. What needs the camera's own HTTP interface — OFF today
+
+**Blocked on infrastructure, not on code.** Measured 2026-08-10 from this
+workstation and from the staging API host: the recorder answers on **RTSP/554
+only**. Ports 80, 443 and the Dahua native port 37777 time out. Until that
+changes, every variable in this section can be set and nothing will answer.
+
+| Capability | Needs |
+|---|---|
+| `deviceInfo` | §2 not required · `CAMERA_DEVICE_HTTP` + `CAMERA_DEVICE_HTTP_ENABLED` + reachability |
+| `playback` | the same |
+| `events` | the same |
+| `stillFrame` (fallback) | the same — used only when no RTSP recorder is configured |
+| `ptz` | the above **plus** `CAMERA_DEVICE_CONTROL_ENABLED` **plus** a PTZ-capable unit **plus** `CAMERA_PTZ_ENABLED` |
+| `presets` | the same as `ptz` |
+
+```
+# 1. Where the recorder's HTTP interface is. The credential is REFERENCED by
+#    environment-variable NAME and never written here, so this value is safe to
+#    paste into a PR or a ticket.
+CAMERA_DEVICE_HTTP={"<relay-authority>":{"baseUrl":"https://<recorder-host>:443","credentialRef":"CAMERA_DEVICE_CRED_MAIN"}}
+
+# 2. The secret itself, set separately, alongside the host's other secrets.
+CAMERA_DEVICE_CRED_MAIN=<username>:<password>
+
+# 3. Reads. Off by default. Nothing contacts a device while this is unset.
+CAMERA_DEVICE_HTTP_ENABLED=true
+
+# 4. Optional tuning.
+CAMERA_DEVICE_HTTP_TIMEOUT_MS=8000
+CAMERA_DEVICE_HTTP_PROBE_TTL_SECONDS=900
+```
+
+### Validation, and what happens when it fails
+
+`CAMERA_DEVICE_HTTP` is validated at startup and every rejection is logged with
+the variable name and the reason. A rejected entry is **dropped, never
+half-used**, and its cameras then report `device-http-not-configured` truthfully
+rather than hanging on a request.
+
+- `baseUrl` must be an `http(s)` **origin** — scheme, host, optional port. A path,
+  query or fragment is rejected.
+- `credentialRef` must look like an environment variable name (`A-Z`, `0-9`, `_`).
+  A credential pasted into this field is **rejected, not used**.
+- The referenced variable must exist and be `username:password`. The split is on
+  the first colon only, so a password may contain colons.
+- Malformed JSON yields no recorders at all.
+
+---
+
+## 4. Arming camera control — needs a named human
+
+```
+CAMERA_DEVICE_CONTROL_ENABLED=true
+```
+
+**This is the only variable in this document that can move physical hardware, and
+it must not be set without a backend lead's sign-off** (Benar or Kyle). It is a
+separate variable from `CAMERA_DEVICE_HTTP_ENABLED` on purpose: turning reads on
+must not arm motors.
+
+Three independent switches must all be on before a PTZ command can be sent —
+`CAMERA_PTZ_ENABLED`, `CAMERA_DEVICE_HTTP_ENABLED` and
+`CAMERA_DEVICE_CONTROL_ENABLED` — and the unit must have told us through §8.1.3
+that it actually pans. All three ship off, and no device has been moved.
+
+While control is off, the adapter's `control` object is `null`: the mutating
+functions are not merely guarded, they do not exist to be called.
+
+**Never implemented, and it must stay that way:** any `configManager.cgi` write,
+`setCurrentTime`, `SetPreset` / `ClearPreset`, tours, patterns, reboot, and any
+barrier or gate command. This integration issues no configuration writes to any
+device.
+
+---
+
+## 5. The lockout budget
+
+A Dahua unit locks an account for **1800 s after 3 failed logins in 30 s**
+(V3.37 §4.7.x). On a unit that also runs ANPR and a barrier, that is half an hour
+of a site's access control gone.
+
+The failure budget is therefore **not configurable**. It counts failures per
+device in the shared cache, stops at **2**, and once spent refuses to send
+anything until the device's own lock time has elapsed — reporting
+`device-http-locked-out` instead of retrying. It is shared across API workers
+(the limit belongs to the device, not to a process) and persistent across
+restarts (a deploy must not hand the budget back).
+
+If the budget is spent, the cause is almost always a wrong credential in
+`CAMERA_DEVICE_CRED_*`. Fix the credential; do not shorten the cooldown.
+
+---
+
+## 6. Reading the descriptor
+
+Each camera in the wall and status responses carries:
+
+```json
+"capabilities": {
+  "liveVideo":  { "state": "supported",   "transport": "RELAY_PLAYER", "reason": null, "detail": null },
+  "stillFrame": { "state": "supported",   "transport": "RTSP_FRAME",   "reason": null, "detail": null },
+  "ptz":        { "state": "unsupported", "transport": null,
+                  "reason": "device-http-not-configured",
+                  "detail": "No direct connection to this camera's recorder is configured on this server." }
+}
+```
+
+**A client should switch on `reason`, never on `detail`.** `detail` is there so a
+surface with nothing better to show has something honest to show.
+
+Reason codes: `not-patrol-cctv-camera`, `camera-inactive`, `no-address`,
+`invalid-address`, `not-a-relay-player-url`, `no-recorder-configured`,
+`no-channel-in-address`, `device-http-not-configured`, `device-http-disabled`,
+`device-http-unreachable`, `device-http-locked-out`, `device-not-probed`,
+`device-no-ptz`, `control-not-enabled`, `no-transport`.
+
+## 7. Adding a transport later
+
+Register one — `registerCameraTransport({ id, provides, evaluate })` — and list
+the capabilities it serves. Registration order is preference order. **No service,
+controller or descriptor change is needed**, which is how an HLS relay, a MediaMTX
+playback URL or an audio path would land: a capability no transport claims already
+answers `no-transport`, and starts answering `supported` the moment something
+claims it.
+
+---
+
+_Written 2026-08-10 alongside the integration layer. Update when the recorder's
+HTTP interface becomes reachable, when a transport is added, or when control is
+armed anywhere._

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@7365admin1/core",
   "license": "MIT",
-  "version": "3.42.3",
+  "version": "3.44.0",
   "author": "7365admin1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -14,7 +14,8 @@
     "release": "yarn run build && changeset publish",
     "lint": "tsc",
     "test:e2e": "yarn build && node --test --test-concurrency=1 --test-timeout=600000 \"test/e2e/*.test.mjs\"",
-    "test:anpr": "tsup src/utils/camera-alert.util.ts src/utils/dahua-protocol.util.ts --format esm --out-dir test/.build/utils --no-dts --silent && node --test \"test/camera-alert.util.test.mjs\" \"test/dahua-protocol.util.test.mjs\""
+    "test:anpr": "tsup src/utils/camera-alert.util.ts src/utils/dahua-protocol.util.ts --format esm --out-dir test/.build/utils --no-dts --silent && node --test \"test/camera-alert.util.test.mjs\" \"test/dahua-protocol.util.test.mjs\"",
+    "test:camera": "tsup src/utils/camera-view.util.ts src/utils/camera-capability.util.ts src/services/camera-device-http.service.ts --format esm --out-dir test/.build --no-dts --silent && node --test \"test/camera-view.util.test.mjs\" \"test/camera-capability.util.test.mjs\" \"test/camera-device-http.test.mjs\" \"test/camera-write-gate.test.mjs\" \"test/camera-entitlement-wiring.test.mjs\""
   },
   "devDependencies": {
     "@changesets/cli": "^2.26.0",