@calebcall/camera-ui-notify 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+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.4.0] - 2026-07-25
+
+### Added
+
+- **Pushover backend** — hosted push to the Pushover app (app token + user key); sends the snapshot
+  as an attachment and maps severity to Pushover priority (Info=0, higher=1).
+- **Telegram backend** — delivery to a chat via a bot (bot token + chat ID); `sendPhoto` with the
+  snapshot when present, else `sendMessage`, with an inline "Open camera" button for the deep link.
+- **Discord backend** — delivery via a channel webhook; a severity-colored embed with the snapshot
+  attached and the title linked to the deep link.
+
+### Security
+
+- **Redact secrets from transport errors.** Telegram's bot token (in the request URL path), a
+  Discord webhook URL (itself a credential), and any secret embedded in a generic webhook URL are
+  no longer leaked into logs when a delivery request fails — request URLs are stripped from
+  `*url.Error` before wrapping.
+
+## [0.3.0] - 2026-07-25
+
+### Added
+
+- **Inline thumbnail image (ntfy).** When a notification carries inline thumbnail bytes (e.g. the
+  NVR's detection snapshot) and no image URL, the ntfy backend uploads it as a file attachment so
+  the image renders in the notification.
+- **Absolute deep links.** A new optional plugin config field, **camera.ui Base URL**, turns the
+  publisher's relative deep link (e.g. `/cameras/<name>?startTs=…`) into an absolute URL so ntfy's
+  tap-through (`Click`) works. Empty base URL leaves the link untouched.
+- **Webhook thumbnail.** The generic webhook backend now includes the thumbnail as `thumbnailBase64`
+  in its JSON payload when present.
+
+### Fixed
+
+- **Gotify visibility.** Severity now maps to Gotify priority 4–10 (Info=4 … Critical=10). Gotify
+  treats priority 0–3 as silent (no system notification), so the previous 0–10 mapping made
+  Info-severity notifications appear to deliver nothing.
+
+### Notes
+
+- Gotify cannot display an inline thumbnail image (it requires a hosted image URL, not raw bytes);
+  images are delivered on ntfy only.
+
+## [0.2.0] - 2026-07-24
+
+### Changed
+
+- **Config-driven single target replaces device registration.** The stock camera.ui UI has no
+  way to *create* a notifier device — `registerDevice` is only ever called by the mobile app's
+  push-registration flow, hardcoded to the official NVR's plugin name, and the generic
+  notification settings panel renders read-only. The plugin's own settings page, however, does
+  render an editable, savable form from any plugin's `StorageSchema`. Notify now holds exactly
+  one target — a selected service (`ntfy`/`gotify`/`webhook`) plus that service's fields — in its
+  own persisted config, set from the plugin's settings page in camera.ui rather than through a
+  device-add flow.
+- **`getDevices` synthesizes the device from config.** Instead of reading a stored device list, it
+  reads the configured service and fields on every call, validates them (`ParseTarget`), and
+  returns a single `sdk.NotifierDevice` (or none, if unconfigured/incomplete). `getDevice` mirrors
+  this for the one synthesized id (`cfg:<service>`).
+- **`registerDevice` / `updateDevice` / `revokeDevice` are now no-ops** (the first returns an
+  error directing users to the plugin's settings page) — targets are configured, not registered.
+  These remain only to satisfy the `Notifier` interface.
+- **`notificationSettings()` returns nothing.** Target configuration now lives on the plugin's
+  config tab; duplicating it in the notification "send test" panel would only confuse.
+
+### Removed
+
+- The device store (`src/store.go`) and its persisted `devices` key — replaced by the
+  `StorageSchema`-based config described above.
+
+Backends (ntfy, Gotify, generic webhook), their config fields, delivery format, and severity
+mapping are unchanged from 0.1.0.
+
+## [0.1.0] - 2026-07-24
+
+Initial release — a fully-local, multi-backend camera.ui `Notifier` plugin.
+
+### Added
+
+- **Notifier plugin** — implements the full `Notifier` RPC surface (`getDevices`, `getDevice`,
+  `registerDevice`, `updateDevice`, `revokeDevice`, `sendNotification`, `notificationSettings`)
+  against a `Notifier`-only contract (`role: Hub`, `interfaces: [Notifier]`).
+- **Pluggable-backend registry** — a `Backend` interface (id, label, config schema, target
+  validation, delivery) with a package-level registry; each backend self-registers from its own
+  `init()`, so adding a new backend later is one new file and a version bump.
+- **Per-device backend selection** — each registered device is bound to one backend and holds
+  that backend's validated config; the registration form is built dynamically from the union of
+  every registered backend's schema, condition-gated on the selected service.
+- **ntfy backend** — publishes to [ntfy.sh](https://ntfy.sh) or a self-hosted server (`server`,
+  `topic`, optional `token`), mapping severity to ntfy's 1–5 priority scale.
+- **Gotify backend** — publishes to a self-hosted [Gotify](https://gotify.net) server (`server`,
+  `token`), mapping severity to Gotify's 0–10 priority scale.
+- **Generic webhook backend** — delivers a JSON payload of the full notification to any HTTP
+  endpoint (`url`, `method` [`POST`/`PUT`], optional custom header) for services without a
+  dedicated backend.
+- **Device persistence** — devices are stored as JSON under the plugin's own `DeviceStorage`,
+  requiring no external database.
+
+[0.2.0]: https://github.com/calebcall/camera-ui-notify/releases/tag/v0.2.0
+[0.1.0]: https://github.com/calebcall/camera-ui-notify/releases/tag/v0.1.0

package/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 calebcall
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,295 @@
+<h1 align="center">Notify</h1>
+
+<p align="center">
+  A fully-local, multi-backend <a href="https://github.com/seydx/camera.ui">camera.ui</a> notifier
+  plugin — delivers notifications to a service you control (<a href="https://ntfy.sh">ntfy</a>,
+  <a href="https://gotify.net">Gotify</a>, Pushover, Telegram, Discord, or a generic webhook),
+  entirely on your own hardware, with no cloud dependency and no license check.
+</p>
+
+---
+
+## Why this exists
+
+camera.ui separates two notification roles:
+
+- **Publishers** (capability `PublishNotifications`) emit events. Our open-source NVR plugin
+  (`@calebcall/camera-ui-nvr-local`) is a publisher — it calls `NotificationManager.Publish` for
+  object-detection events.
+- **Notifiers** (interface `Notifier`) own delivery *devices* and actually deliver notifications.
+  The host's `NotificationManager.notify()` fans every notification out to **all** running plugins
+  implementing `Notifier`.
+
+There is intentionally no notifier in the open ecosystem: the closed, official NVR bundled a
+notifier that pushed to the camera.ui mobile app through camera.ui's proprietary FCM/APNs cloud
+relay — a license-gated path we neither have credentials for nor can replicate. This plugin takes
+the only fully-local road to real background push instead: delivering to a push/webhook service
+*you* run or control.
+
+This plugin is a pure **notifier**. It is decoupled from any single publisher — it delivers
+notifications from **any** publisher, including our NVR plugin's detection events and camera.ui's
+own system notifications, not just one plugin's output.
+
+## How it works
+
+One plugin, contract `interfaces: [Notifier]`, built around a pluggable-backend (strategy) pattern:
+
+- A `Backend` interface abstracts one delivery service (id, label, config schema, target
+  validation, and delivery).
+- A package-level registry maps each backend's stable id to its implementation; every backend
+  self-registers from its own `init()`.
+- The plugin holds **one active target** in its own persisted config (`StorageSchema`): which
+  service is selected, plus that service's validated fields. `getDevices` synthesizes a single
+  `sdk.NotifierDevice` from this config on every call — there is no device registry.
+- `sendNotification` dispatches the synthesized device to its backend's `Send`. A backend failure
+  is logged and returned to the host.
+
+### Why config, not device registration
+
+Earlier versions of this plugin modeled targets as registrable `NotifierDevice`s, the way
+camera.ui's own mobile-push notifier does. That model turned out to be unreachable from the stock
+UI: `registerDevice` is only ever called by the camera.ui mobile app's push-registration flow,
+which is hardcoded to the official NVR's plugin name. The generic notification settings panel
+renders `notificationSettings()` read-only — it has no "add a device" affordance for third-party
+plugins. The one part of the stock UI that **does** render an editable, savable form for a
+third-party plugin is its own settings page, which renders whatever `StorageSchema` the plugin
+declares. So Notify now models its target as plugin config instead of a device: you configure it
+once, in the plugin's own settings, and `getDevices` synthesizes the device the host's
+`Notifier` interface expects from that config.
+
+Adding a new backend later is **one new file** — `src/backend/<name>.go` implementing `Backend`
+plus `Register(...)` in its `init()` — and a version bump. No new plugin, no core change, no
+changes to `plugin.go`.
+
+## Backends (v1)
+
+Severity is mapped consistently across backends via `backend.PriorityScale`, which spreads
+camera.ui's four severity levels (`info` → `warn` → `error` → `critical`) evenly across each
+backend's native priority range, `info` at the low end and `critical` at the high end.
+
+### ntfy
+
+Publishes to [ntfy.sh](https://ntfy.sh) or a self-hosted ntfy server.
+
+| Field    | Required | Default              | Notes                                              |
+| -------- | -------- | --------------------- | --------------------------------------------------- |
+| `server` | no       | `https://ntfy.sh`     | Base URL of the ntfy server. Trailing `/` trimmed. |
+| `topic`  | yes      | —                     | The ntfy topic to publish to.                      |
+| `token`  | no       | —                     | Access token for a protected/self-hosted topic, sent as `Authorization: Bearer <token>`. |
+
+Delivery: `POST {server}/{topic}` with the notification body as the request body, plus `Title`,
+`Priority` (1–5, from severity), `Click` (deep link, if set), and `Attach`/`Icon` (image URL, if
+set) headers.
+
+### Gotify
+
+Publishes to a self-hosted [Gotify](https://gotify.net) server.
+
+| Field    | Required | Notes                                          |
+| -------- | -------- | ----------------------------------------------- |
+| `server` | yes      | Base URL of the Gotify server. Trailing `/` trimmed. |
+| `token`  | yes      | Gotify application token, used to authenticate published messages. |
+
+Delivery: `POST {server}/message?token={token}` with a JSON body `{title, message, priority}`
+(priority 0–10, from severity), plus a `client::notification.click` extra for the deep link and a
+`bigImageUrl` extra when an image URL is set.
+
+### Generic webhook
+
+Delivers to any HTTP endpoint you provide — the fallback for anything without a dedicated backend.
+
+| Field         | Required | Default | Notes                                                         |
+| ------------- | -------- | ------- | -------------------------------------------------------------- |
+| `url`         | yes      | —       | Endpoint that receives the notification.                       |
+| `method`      | no       | `POST`  | `POST` or `PUT`.                                                |
+| `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}`.
+
+### Pushover
+
+Hosted push to the [Pushover](https://pushover.net) app.
+
+| Field    | Required | Notes                                          |
+| -------- | -------- | ---------------------------------------------- |
+| `token`  | yes      | Pushover application API token/key.            |
+| `user`   | yes      | Your Pushover user or group key.               |
+
+Delivery: `POST https://api.pushover.net/1/messages.json` with title/message and a priority
+(Info→0 normal, everything higher→1 high; never emergency). The snapshot **image** is sent as an
+`attachment`, and an absolute deep link becomes a supplementary `url`.
+
+### Telegram
+
+Delivers to a chat via a [Telegram bot](https://core.telegram.org/bots).
+
+| Field   | Required | Notes                                                    |
+| ------- | -------- | -------------------------------------------------------- |
+| `token` | yes      | Bot token from @BotFather.                               |
+| `chat`  | yes      | Chat ID to deliver to.                                   |
+
+Delivery: `sendPhoto` (with the snapshot **image** + caption) when a thumbnail is present, otherwise
+`sendMessage`. An absolute deep link is added as an inline "Open camera" button.
+
+### Discord
+
+Delivers to a channel via a Discord [webhook](https://support.discord.com/hc/en-us/articles/228383668).
+
+| Field     | Required | Notes                                   |
+| --------- | -------- | --------------------------------------- |
+| `webhook` | yes      | Channel webhook URL.                    |
+
+Delivery: a rich embed (title, body, severity color — blue/yellow/red) with the snapshot **image**
+attached; an absolute deep link makes the title a link.
+
+> **Images:** ntfy, Pushover, Telegram, and Discord all render the detection snapshot. Gotify is
+> text + link only (it needs a hosted image URL, which this fully-local plugin doesn't provide).
+
+> **Secrets in logs:** transport failures never log the bot token / webhook URL / other
+> URL-embedded secret — request URLs are redacted from delivery errors.
+
+## Configuring your target (v1: one active target)
+
+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`,
+   or `Discord`) 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.
+
+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).
+
+## Tech stack
+
+- **Go** (matches the NVR plugin; same build/deploy toolchain).
+- **camera.ui SDK (Go)** for the plugin runtime, the `Notifier` RPC surface, and device storage.
+- Delivery via each backend's plain HTTP API using the Go stdlib `net/http` — no third-party HTTP
+  client libraries.
+- Config persistence via the plugin's own `DeviceStorage`, holding the selected service and its
+  fields as declared by `StorageSchema()` — no SQLite; it's a handful of scalar values.
+
+## Prerequisites
+
+- **Go 1.26+** (to build the plugin binary).
+- **Node.js 22+** and the plugin's dev dependencies (`npm install`) to produce the `contract.cjs`
+  bundle via the camera.ui CLI.
+- A running camera.ui instance you control (the host where the plugin gets installed).
+
+## Build & deploy locally
+
+camera.ui loads the **built artifact**, not source — a `git pull` alone does nothing. You must
+build the bundle (`contract.cjs` + the platform binary) and copy it into the install slot.
+
+The install slot is:
+
+```
+<camera.ui-install>/plugins/@calebcall/camera-ui-notify/
+```
+
+and the plugin's config (the selected service and its fields) lives under
+`<camera.ui-install>/volume/plugins/storage/@calebcall/camera-ui-notify/` — reinstalling the code
+does not touch it.
+
+> **Unlike the NVR plugin**, there is no hardcoded-package-id requirement here: the camera.ui host
+> discovers notifiers by the `Notifier` **interface** declared in the plugin's contract, not by a
+> fixed package name. This plugin can be installed under its own real name/namespace.
+
+### Option A — build natively on the server (preferred)
+
+If Go 1.26+ and Node are available on the host, build there and skip the cross-compile round-trip:
+
+```bash
+# 1. Get the latest source
+cd ~/path/to/plugins && git pull
+cd camera-ui-notify
+npm install                 # first time only — pulls the camera.ui CLI bundler
+
+# 2. Build the bundle (produces bundle/{contract.cjs, package.json, dist/bin/plugin})
+npm run bundle:dev
+
+# 3. Install into the @calebcall/camera-ui-notify slot
+D=<camera.ui-install>/plugins/@calebcall/camera-ui-notify
+mkdir -p "$D" && rm -rf "$D"/* && cp -a bundle/. "$D/"
+
+# 4. First time only: enable it — remove the "@calebcall/camera-ui-notify" line
+#    from disabledPlugins in <camera.ui-install>/volume/camera.ui.yaml
+
+# 5. Restart camera.ui
+systemctl restart cameraui   # or however your instance is managed
+```
+
+### Option B — cross-compile from a workstation
+
+Build a statically-linked Linux binary locally, then ship the bundle to the server:
+
+```bash
+cd camera-ui-notify
+
+# 1. Produce contract.cjs (+ package.json) under bundle/
+npm install
+npm run bundle:dev
+
+# 2. Cross-compile the Linux binary into the bundle's dev path
+GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \
+  go build -ldflags "-s -w" -o bundle/dist/bin/plugin ./src/
+chmod 755 bundle/dist/bin/plugin
+
+# 3. Ship it (strip macOS junk so the server dir stays clean)
+COPYFILE_DISABLE=1 tar czf /tmp/notify-install.tgz -C bundle .
+scp /tmp/notify-install.tgz root@YOUR_SERVER:/tmp/
+
+# 4. On the server: install into the slot, enable (first time), restart
+ssh root@YOUR_SERVER '
+  D=<camera.ui-install>/plugins/@calebcall/camera-ui-notify
+  mkdir -p "$D" && rm -rf "$D"/* && tar xzf /tmp/notify-install.tgz -C "$D"
+  systemctl restart cameraui
+'
+```
+
+Set `GOARCH=arm64` for ARM hosts. The binary is resolved from the dev path
+`<slot>/dist/bin/plugin` before any platform `node_modules` package, so no npm publish is involved.
+
+### Verify it loaded and is being used
+
+Tail the camera.ui log after restart:
+
+```bash
+grep -iE "Notify|Spawning Go|notify: rpc" <camera.ui-install>/volume/camera.ui.log | tail
+```
+
+You want to see the plugin spawn (`Spawning Go plugin ... dist/bin/plugin`) **and** the host
+actually calling into it — e.g. `notify: rpc getDevices` / `notificationSettings` /
+`sendNotification`.
+
+## Adding a new backend
+
+1. Create `src/backend/<name>.go` implementing the `Backend` interface (`ID`, `Label`, `Schema`,
+   `ParseTarget`, `Send`) — see `ntfy.go`, `gotify.go`, or `webhook.go` for the shape.
+2. Gate every schema field with `Condition: []sdk.SchemaCondition{{Key: "service", Value: ID()}}`
+   so it only renders when the new backend is selected.
+3. Call `backend.Register(new<Name>())` from an `init()` function in the same file.
+4. Bump the version in `package.json`.
+
+Nothing outside `src/backend/` needs to change — the registry, the `service` enum, and the
+dispatch logic in `notifier.go` all pick up the new backend automatically.
+
+## Development
+
+```bash
+go test ./src/...                 # full suite
+go test ./src/... -race -count=1  # race detector
+```
+
+## License
+
+[MIT](./LICENSE.md).

package/package.json

@@ -0,0 +1,61 @@
+{
+  "displayName": "Notify",
+  "name": "@calebcall/camera-ui-notify",
+  "version": "0.4.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.",
+  "author": "calebcall (https://github.com/calebcall/camera-ui-notify)",
+  "main": "./main.go",
+  "type": "commonjs",
+  "scripts": {
+    "build": "rimraf dist && go build -o /dev/null ./src/",
+    "bundle": "npm run build && cui bundle",
+    "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/...",
+    "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",
+    "publish:latest": "npm i --save --force && npm run bundle && cui publish --latest",
+    "test": "go test ./...",
+    "update": "updates --update ./"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/calebcall/camera-ui-notify/issues"
+  },
+  "engines": {
+    "camera.ui": ">=2.0.15",
+    "node": ">=22.0.0"
+  },
+  "homepage": "https://github.com/calebcall/camera-ui-notify/tree/main#readme",
+  "keywords": [
+    "camera-ui-plugin",
+    "notifier",
+    "notifications",
+    "ntfy",
+    "gotify",
+    "webhook",
+    "local"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/calebcall/camera-ui-notify.git"
+  },
+  "os": [],
+  "cpu": [],
+  "optionalDependencies": {
+    "@calebcall/camera-ui-notify-darwin-arm64": "0.4.0",
+    "@calebcall/camera-ui-notify-darwin-amd64": "0.4.0",
+    "@calebcall/camera-ui-notify-linux-amd64": "0.4.0",
+    "@calebcall/camera-ui-notify-linux-arm64": "0.4.0",
+    "@calebcall/camera-ui-notify-windows-amd64": "0.4.0",
+    "@calebcall/camera-ui-notify-windows-arm64": "0.4.0",
+    "@calebcall/camera-ui-notify-linux-amd64-musl": "0.4.0",
+    "@calebcall/camera-ui-notify-linux-arm64-musl": "0.4.0"
+  },
+  "files": [
+    "bundle.zip",
+    "CHANGELOG.md"
+  ]
+}