@calebcall/camera-ui-notify 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,100 @@ All notable changes to **Notify** are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.8.0] - 2026-08-11
+
+### Fixed
+
+- **No more duplicate notifications for AI descriptions.** camera.ui announces a detection, then
+  republishes the same notification once the AI description is ready — same `tag`, plus
+  `silent: true` to mark it as an update rather than a new alert. Both fields were previously
+  ignored, so every detection arrived twice, both times with sound. Now:
+  - **Telegram** and **Discord** replace the original message in place (`editMessageText` /
+    `editMessageCaption`, `PATCH .../messages/{id}`), so one notification's text improves rather
+    than a second one appearing. Message ids are held in memory per tag for 15 minutes; after a
+    restart, or if the original was deleted, the update falls back to a new quiet message. Only
+    the `silent` follow-up replaces — detection tags repeat across events, so a new alert reusing
+    a tag always posts a new message rather than rewriting chat history.
+  - **ntfy** (priority `1`), **Gotify** (priority `3`) and **Pushover** (priority `-1`) deliver the
+    update without sound or vibration.
+  - **Grafana** resolves the update onto the event it already opened: annotations mode patches the
+    existing annotation's text, Alertmanager and IRM modes re-send under the same fingerprint so
+    the alert updates instead of a second one firing.
+  - The **generic webhook** payload forwards the new `silent` field alongside the existing `tag`.
+  - `critical` notifications ignore `silent` and always alert, per the SDK contract.
+
+- **README no longer documents `grafana_irm_ttl`.** The field was removed from the code in 0.7.1
+  when IRM turned out to ignore `endsAt`, but its row survived in the config table — directly
+  contradicting the paragraph below it stating that IRM groups do not auto-resolve.
+
+### Added
+
+- **"Follow-up updates" setting** (`silent_updates`) — `Deliver quietly (no sound)` (default) or
+  `Skip the update entirely`, for anyone who wants exactly one notification per event on the
+  backends that can't replace a delivered message. Backends that replace in place still receive
+  the update under `skip`, since it adds no entry to the notification list.
+
+### Changed
+
+- **camera.ui Go SDK bumped to v1.2.22** (from v1.2.6) for `Notification.Silent`.
+- **Linting consolidated on golangci-lint**, configured by a new `.golangci.yml`. `npm run lint`
+  previously chained `staticcheck && golangci-lint run`, so a staticcheck finding short-circuited
+  the `&&` and golangci-lint never ran at all. golangci-lint already bundles staticcheck's
+  analyzers, so the standalone binary is gone from the script; the config excludes three
+  deliberate idioms (`defer resp.Body.Close()`, and nil-`Context` / De Morgan findings in tests)
+  and `npm run lint` now reports zero issues.
+- **`package.json` description now lists every backend.** It had said "ntfy, Gotify, or a generic
+  webhook" since 0.4.0, omitting Pushover, Telegram, Discord and Grafana. This is the text npm
+  shows on the package listing. ([#29](https://github.com/calebcall/camera-ui-notify/issues/29))
+
+## [0.7.1] - 2026-08-02
+
+### Fixed
+
+- **Alertmanager mode: documented the required path prefix.** Mimir and Grafana Cloud serve the
+  Alertmanager API under a prefix (`/alertmanager` by default); a standalone Alertmanager serves it
+  at the root. 0.7.0's field placeholder and README both showed a bare host, so configuring it the
+  documented way produced `404 page not found` on every send. The README now gives both forms side
+  by side, and the field description and placeholder show the Grafana Cloud shape. No code was
+  wrong here — the documentation was.
+- **A 404 from Alertmanager now explains itself.** Go's default mux answers with a bare
+  `404 page not found`, which says nothing about the missing prefix that caused it. The error now
+  adds that hint. Other statuses are untouched.
+- **A pasted full endpoint is accepted.** Alertmanager's own docs show the complete
+  `.../api/v2/alerts` URL, so copying it into the base-URL field is the obvious mistake; a trailing
+  `/api/v2/alerts` is now trimmed rather than producing `/api/v2/alerts/api/v2/alerts`.
+- **Documented where Grafana Cloud Alertmanager credentials come from.** The username is the
+  numeric Alertmanager instance ID from the Cloud portal; the password is an Access Policy token
+  (`glc_...`) with the `alerts:write` scope — *not* a Grafana service-account token (`glsa_...`),
+  which authenticates to Grafana rather than to the Alertmanager.
+
+### Changed
+
+- **Alertmanager mode no longer sends `startsAt`**, letting Alertmanager stamp it from its own
+  clock. The alert's start time is now correct even on a host whose clock has drifted.
+- **`grafana_ttl` default raised from 300 to 900 seconds.** `endsAt` must be absolute — the
+  Alertmanager API has no relative form — so it is still derived from the camera.ui host's clock. A
+  host running more than `grafana_ttl` behind the Alertmanager sends an `endsAt` already in the
+  past, and the alert is accepted with a `200`, resolved on arrival, and never appears as active —
+  a silent no-op that reads as success. 15 minutes gives that failure real margin where 5 did not,
+  and the README now names the symptom and the fix (keep the host in NTP sync).
+
+### Removed
+
+- **`grafana_irm_ttl` and the IRM `endsAt` experiment, both added in 0.7.0.** They did nothing. IRM
+  decides whether a group is resolved from a template on the payload's status — its default is
+  `{{ payload.status == "resolved" }}` — and ignores `endsAt` entirely, so no value in a single
+  firing request can close a group; only a second request can. IRM alerts once again carry the
+  documented never-resolves sentinel `0001-01-01T00:00:00Z`, which states the actual behaviour
+  instead of implying an auto-close that never happens, and the README says plainly that groups are
+  closed by hand.
+
+  A delayed resolve was considered and rejected: it would require a background timer and per-event
+  state in a plugin that is otherwise one stateless POST per event, and a restart would strand the
+  group open regardless.
+
 ## [0.7.0] - 2026-08-02
 
 ### Changed

package/README.md

@@ -69,7 +69,7 @@ Delivers to any HTTP endpoint you provide — the fallback for anything without
 | `headerName`  | no       | —       | Optional custom header name (e.g. for a shared secret). Requires `headerValue` if set. |
 | `headerValue` | no       | —       | Value of the custom header. Requires `headerName` if set.       |
 
-Delivery: `{method} {url}` with `Content-Type: application/json` and (if configured) the custom header, carrying a JSON body of `{title, subtitle, body, severity, tag, imageUrl, deepLink, data, createdAt, thumbnailBase64}`.
+Delivery: `{method} {url}` with `Content-Type: application/json` and (if configured) the custom header, carrying a JSON body of `{title, subtitle, body, severity, tag, silent, imageUrl, deepLink, data, createdAt, thumbnailBase64}`.
 
 ### Pushover
 
@@ -115,13 +115,12 @@ different services, so each has its own connection fields.
 | `grafana_server`        | yes      | annotations   | Base URL of the Grafana instance. Trailing `/` trimmed.   |
 | `grafana_token`         | yes      | annotations   | Service-account token, sent as `Authorization: Bearer <token>`. |
 | `grafana_tags`          | no       | annotations   | Comma-separated extra tags.                               |
-| `grafana_am_url`        | yes      | alertmanager  | Base URL of the **Alertmanager**, not of Grafana. Trailing `/` trimmed. |
-| `grafana_am_user`       | no       | alertmanager  | Basic-auth username. For Grafana Cloud, the Alertmanager instance ID. |
-| `grafana_am_password`   | no       | alertmanager  | Basic-auth password. For Grafana Cloud, an API token. Required if a username is set, and vice versa. |
+| `grafana_am_url`        | yes      | alertmanager  | Base URL of the **Alertmanager**, not of Grafana — **including any path prefix** (see below). A pasted `.../api/v2/alerts` endpoint is accepted and trimmed. |
+| `grafana_am_user`       | no       | alertmanager  | Basic-auth username. For Grafana Cloud, the numeric Alertmanager instance ID. |
+| `grafana_am_password`   | no       | alertmanager  | Basic-auth password. For Grafana Cloud, an Access Policy token with the `alerts:write` scope. Required if a username is set, and vice versa. |
 | `grafana_alertname`     | no       | alertmanager  | `alertname` label. Defaults to `CameraUINotification`.    |
-| `grafana_ttl`           | no       | alertmanager  | Seconds before Alertmanager auto-resolves the alert. Default `300`, minimum `30`. |
+| `grafana_ttl`           | no       | alertmanager  | Seconds before Alertmanager auto-resolves the alert. Default `900`, minimum `30`. |
 | `grafana_irm_url`       | yes      | irm           | Inbound webhook URL of an IRM / OnCall integration. The token is in the URL, so it is masked and kept out of every error message. |
-| `grafana_irm_ttl`       | no       | irm           | Seconds before the alert is eligible to auto-resolve. Default `300`, minimum `30`. Whether IRM acts on it depends on the integration's templates. |
 
 **Annotations** — `POST {server}/api/annotations` with a point-in-time, organization-wide
 annotation tagged `camera.ui`, `camera:<name>`, `severity:<level>`, plus your extra tags. Surface it
@@ -140,8 +139,35 @@ Cloud's hosted Alertmanager (username = instance ID, password = API token).
 > rule evaluation. Point this at a real Alertmanager. (Versions 0.6.0–0.6.1 targeted Grafana here
 > and always failed with `400 bad request data`.)
 
-`endsAt` is `startsAt + grafana_ttl`, which lets Alertmanager auto-resolve the alert without a
-second request. Labels are `alertname`, `source=camera.ui`, `severity` (camera.ui's own four
+> **Get the URL right — this is the most common way to misconfigure this mode.** Mimir and Grafana
+> Cloud serve the Alertmanager API under a path prefix, `/alertmanager` by default; a standalone
+> Alertmanager serves it at the root. Omit the prefix and every send fails with a bare
+> `404 page not found`.
+>
+> | Target | Enter | Resulting POST |
+> | --- | --- | --- |
+> | Grafana Cloud / Mimir | `https://alertmanager-prod-xx.grafana.net/alertmanager` | `…/alertmanager/api/v2/alerts` |
+> | Standalone Alertmanager | `http://alertmanager:9093` | `…/api/v2/alerts` |
+>
+> **Grafana Cloud credentials** come from two different places. The **username** is the numeric
+> Alertmanager instance ID, shown with the URL on the Alertmanager details page in the Cloud
+> portal. The **password** is an **Access Policy token** (`glc_…`) carrying the `alerts:write`
+> scope, created under Access Policies — *not* a Grafana service-account token (`glsa_…`), which
+> authenticates to Grafana rather than to the Alertmanager.
+
+`endsAt` is `now + grafana_ttl`, which lets Alertmanager auto-resolve the alert without a
+second request. `startsAt` is deliberately not sent — Alertmanager stamps it from its own clock.
+
+> **If sends succeed but no alert appears, check the clock.** `endsAt` has to be absolute
+> (Alertmanager's API has no relative form), so it is computed from the camera.ui host's clock. A
+> host running more than `grafana_ttl` *behind* the Alertmanager sends an `endsAt` already in the
+> past: the alert is accepted with a `200`, resolved on arrival, and never shows as active. The
+> symptom is a clean `notify: delivered` in the log and an empty
+> `GET {alertmanager}/api/v2/alerts`. Keep the host in NTP sync. The 900-second default exists to
+> give that failure some margin.
+>
+> Second, gentler trap: alerts self-resolve after `grafana_ttl` and drop off the active list, so
+> when testing, look within the window rather than an hour later. Labels are `alertname`, `source=camera.ui`, `severity` (camera.ui's own four
 levels, verbatim), `camera`, `camera_id`, and a unique `event_id` — the last of these matters, because
 Alertmanager deduplicates on the label set and without it two detections on one camera inside the
 TTL window would collapse into a single alert. The absolute deep link becomes `generatorURL`,
@@ -157,11 +183,14 @@ labels/annotations/`generatorURL`/`imageURL`, `groupKey`, `commonLabels`, `exter
 
 Alert groups are keyed **per camera** — `camera.ui:<camera>`, falling back to `camera.ui` for a
 notification that names no camera — so one busy camera can't bury a quiet one. Within a group each
-event keeps its own `fingerprint`, so detections stay individually visible. Each alert carries a
-future `endsAt` (`startsAt + grafana_irm_ttl`), the same way Alertmanager mode expresses
-"resolves on its own at this time"; whether IRM acts on it depends on the integration's templates,
-and if it does not, groups stay open until you resolve them by hand. There is still no follow-up
-`state: "ok"` request — every mode is one stateless POST per event.
+event keeps its own `fingerprint`, so detections stay individually visible.
+
+**IRM groups do not auto-resolve.** IRM decides that from a template on the payload's status — its
+default is `{{ payload.status == "resolved" }}` — so a group closes only when a *second* request
+arrives saying so. `endsAt` is ignored, which is why alerts carry the documented never-resolves
+sentinel rather than a future time that would imply a close that never comes. This plugin sends one
+stateless POST per event and no follow-up, by design: a delayed resolve would mean a background
+timer and per-event state, and a restart would strand the group open anyway. Close them in IRM.
 
 > **Camera names:** `camera` carries the camera's display name, taken from `Data["cameraName"]`
 > when a publisher supplies one and otherwise from the deep link, which camera.ui routes by name.
@@ -178,6 +207,32 @@ and if it does not, groups stay open until you resolve them by hand. There is st
 > **Secrets in logs:** transport failures never log the bot token / webhook URL / other
 > URL-embedded secret — request URLs are redacted from delivery errors.
 
+## Follow-up updates (AI descriptions)
+
+camera.ui announces a detection immediately, then republishes the same notification a few seconds later once the AI description is ready. Both publishes carry the same `tag` (the collapse key), and the second carries `silent: true`, meaning *this only updates the first one — don't alert again*.
+
+Handled per backend, according to what each platform can actually do:
+
+| Backend         | Follow-up behaviour                                                                  |
+| --------------- | ------------------------------------------------------------------------------------ |
+| Telegram        | **Replaces** the original message (`editMessageText` / `editMessageCaption`).         |
+| Discord         | **Replaces** the original message (`PATCH .../messages/{id}`).                        |
+| Grafana         | **Revises** the record it already filed — see below.                                  |
+| ntfy            | Delivered at priority `1` — visible, no sound or vibration.                           |
+| Gotify          | Delivered at priority `3` — joins the in-app list, raises no system notification.      |
+| Pushover        | Delivered at priority `-1` (quiet) — no sound or vibration.                            |
+| Generic webhook | `silent: true` is forwarded in the JSON payload; your endpoint decides.               |
+
+Grafana revises per mode: **annotations** patches the annotation it created (`PATCH /api/annotations/:id`), so the dashboard keeps one marker at the detection's own timestamp whose text improves. **Alertmanager** and **IRM** re-file under the `event_id` / `alert_uid` the first alert used — that identity is what each surface deduplicates on, so the existing alert or group picks up the description instead of a second one firing. When the publisher supplies its own `Data["eventId"]`, that id is authoritative and the two publishes already share it, so those modes update correctly even across a plugin restart.
+
+The replacing backends therefore show **one** notification whose text improves in place. The message id is remembered in memory per tag for 15 minutes; after a plugin restart, or if the original message was deleted, the update is delivered as a new (quiet) message instead of being lost.
+
+Only the `silent` follow-up replaces. Detection tags repeat across events (`motion:cam-1` is the same tag every time that camera sees something), so a *new* alert reusing a tag always posts a new message — your chat history is never rewritten by a later event.
+
+**Critical alerts ignore `silent`** — a `critical` severity notification always alerts, per the SDK contract.
+
+If you would rather never see the follow-up on a backend that can't replace, set **Follow-up updates** to `Skip the update entirely` in the plugin settings. Backends that replace in place still receive it under that setting, since editing adds nothing to the notification list — with the one caveat that a lost message id (restart, deleted message) turns that edit into a new quiet message.
+
 ## Configuring your target (v1: one active target)
 
 There is no "add device" flow. Instead, configure the plugin itself:
@@ -185,7 +240,8 @@ There is no "add device" flow. Instead, configure the plugin itself:
 1. Open the **Notify** plugin's page in camera.ui (Plugins → Notify).
 2. In its settings, pick a **Service** (`ntfy`, `Gotify`, `Generic webhook`, `Pushover`, `Telegram`, `Discord`, or `Grafana`) from the dropdown built from the registered backends.
 3. Fill in that service's fields — only the selected service's fields are shown; the rest are condition-gated out.
-4. Save. The config is validated (`ParseTarget`) the next time a notification is dispatched; `getDevices` then synthesizes one delivery target from it, and notifications from any publisher are delivered there.
+4. Optionally set **Follow-up updates** (see [Follow-up updates](#follow-up-updates-ai-descriptions)) — defaults to delivering the AI description quietly.
+5. Save. The config is validated (`ParseTarget`) the next time a notification is dispatched; `getDevices` then synthesizes one delivery target from it, and notifications from any publisher are delivered there.
 
 This is a **single, instance-wide target** in v1 — there's no way to register several devices at once. Changing the config replaces the previous target rather than adding to it. Delivery for that one target is a single request per notification (no fan-out to worry about, since there's only one device).
 
@@ -288,9 +344,24 @@ dispatch logic in `notifier.go` all pick up the new backend automatically.
 
 ```bash
 go test ./src/...                 # full suite
-go test ./src/... -race -count=1  # race detector
+go test ./src/... -race -count=1  # race detector (needs cgo: apt-get install gcc)
+npm run lint                      # golangci-lint, configured by .golangci.yml
+npm run format                    # gofmt + go fix
 ```
 
+Linting is golangci-lint only. It bundles staticcheck's analyzers (`SA`/`S`/`ST`/`QF`), so running
+the standalone `staticcheck` binary alongside it only duplicates findings — and, being a separate
+tool, it can't read the path-scoped exclusions in `.golangci.yml`.
+
+```bash
+go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
+```
+
+`.golangci.yml` excludes three deliberate idioms, each scoped as narrowly as the linter allows so
+the check stays live everywhere else: `defer resp.Body.Close()` (errcheck), and — in `_test.go`
+only — passing a nil `Context` to exercise each backend's `ctx == nil` fallback (SA1012) and the
+`!(a <= b && b <= c)` monotonicity assertions (QF1001).
+
 ## License
 
 [MIT](./LICENSE.md).

package/package.json

@@ -1,8 +1,8 @@
 {
   "displayName": "Notify",
   "name": "@calebcall/camera-ui-notify",
-  "version": "0.7.0",
-  "description": "A fully-local, multi-backend camera.ui notifier plugin: delivers notifications to ntfy, Gotify, or a generic webhook, entirely on your own hardware with no cloud dependency.",
+  "version": "0.8.0",
+  "description": "A fully-local, multi-backend camera.ui notifier plugin: delivers notifications to ntfy, Gotify, Pushover, Telegram, Discord, Grafana, or a generic webhook, entirely on your own hardware with no cloud dependency.",
   "author": "calebcall (https://github.com/calebcall/camera-ui-notify)",
   "main": "./main.go",
   "type": "commonjs",
@@ -12,7 +12,7 @@
     "bundle:dev": "npm run build && cross-env MODE=development cui bundle",
     "format": "gofmt -w ./src/* && go fix ./src/...",
     "install-updates": "npm i --save --force && go mod tidy",
-    "lint": "staticcheck ./src/... && golangci-lint run ./src/...",
+    "lint": "golangci-lint run ./src/...",
     "prepublishOnly": "node -e \"if(!process.env.SAFE_PUBLISH){console.error('Error: Please use @camera.ui/cli to publish the plugin:\\n  npm run publish:alpha\\n  npm run publish:beta\\n  npm run publish:latest\\n');process.exit(1)}\"",
     "publish:alpha": "npm i --save --force && npm run bundle && cui publish --alpha",
     "publish:beta": "npm i --save --force && npm run bundle && cui publish --beta",
@@ -48,14 +48,14 @@
     "protocolLevel": 1
   },
   "optionalDependencies": {
-    "@calebcall/camera-ui-notify-darwin-arm64": "0.7.0",
-    "@calebcall/camera-ui-notify-darwin-amd64": "0.7.0",
-    "@calebcall/camera-ui-notify-linux-amd64": "0.7.0",
-    "@calebcall/camera-ui-notify-linux-arm64": "0.7.0",
-    "@calebcall/camera-ui-notify-windows-amd64": "0.7.0",
-    "@calebcall/camera-ui-notify-windows-arm64": "0.7.0",
-    "@calebcall/camera-ui-notify-linux-amd64-musl": "0.7.0",
-    "@calebcall/camera-ui-notify-linux-arm64-musl": "0.7.0"
+    "@calebcall/camera-ui-notify-darwin-arm64": "0.8.0",
+    "@calebcall/camera-ui-notify-darwin-amd64": "0.8.0",
+    "@calebcall/camera-ui-notify-linux-amd64": "0.8.0",
+    "@calebcall/camera-ui-notify-linux-arm64": "0.8.0",
+    "@calebcall/camera-ui-notify-windows-amd64": "0.8.0",
+    "@calebcall/camera-ui-notify-windows-arm64": "0.8.0",
+    "@calebcall/camera-ui-notify-linux-amd64-musl": "0.8.0",
+    "@calebcall/camera-ui-notify-linux-arm64-musl": "0.8.0"
   },
   "files": [
     "bundle.zip",