@calebcall/camera-ui-notify 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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).
 
+## [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

@@ -115,11 +115,11 @@ 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. |
 
@@ -140,8 +140,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 +184,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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "displayName": "Notify",
   "name": "@calebcall/camera-ui-notify",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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.",
   "author": "calebcall (https://github.com/calebcall/camera-ui-notify)",
   "main": "./main.go",
@@ -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.7.1",
+    "@calebcall/camera-ui-notify-darwin-amd64": "0.7.1",
+    "@calebcall/camera-ui-notify-linux-amd64": "0.7.1",
+    "@calebcall/camera-ui-notify-linux-arm64": "0.7.1",
+    "@calebcall/camera-ui-notify-windows-amd64": "0.7.1",
+    "@calebcall/camera-ui-notify-windows-arm64": "0.7.1",
+    "@calebcall/camera-ui-notify-linux-amd64-musl": "0.7.1",
+    "@calebcall/camera-ui-notify-linux-arm64-musl": "0.7.1"
   },
   "files": [
     "bundle.zip",