test(notifications): cover tap targets, quick-answer tokens and the action route; document them

This commit is contained in:
Marc-André Bombeck committed 2026-10-11 12:33:02 +02:00
1 parent 40e66bf027
commit 5435890275
16 files changed
+1300 -2

No files matched your search

+112
View File
@@ -13103,6 +13103,7 @@ paths:
- WEB
- TELEGRAM
- DAYLIO
- NOTIFICATION
- in: query
name: from
schema:
@@ -21632,6 +21633,56 @@ paths:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
/api/notifications/action/{token}:
post:
tags:
- Notifications
summary: Log a quick answer tapped inside a notification
description: "Called by a notification app (ntfy `http` action), never by a signed-in client: the signed path token is
the only credential. The token is bound to one user and one answer, expires six hours after the reminder was
sent, and is single-use across all answers offered on that reminder. Rate-limited per client address before the
token is read. Writes a mood entry with source `NOTIFICATION`; refused with 403 when the mood module is off."
parameters:
- in: path
name: token
schema:
type: string
description: Signed action token from the notification's URL.
required: true
description: Signed action token from the notification's URL.
responses:
"200":
description: The answer was logged.
content:
application/json:
schema:
$ref: "#/components/schemas/NotificationActionResponse"
"401":
description: Invalid token (forged, altered, or unknown user).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"403":
description: The mood module is turned off for this account.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"409":
description: This reminder was already answered.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"410":
description: The answer expired.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"422": *a4
"429": *a5
/api/notifications/preferences:
get:
tags:
@@ -27417,6 +27468,14 @@ components:
properties:
clientManaged:
type: boolean
content:
type: object
properties:
detail:
type: string
enum:
- generic
- detailed
baseUpdatedAt:
description: "Optimistic-concurrency base token: the `updatedAt` the client last read for this resource. Omit it for the
legacy unconditional write (older clients are unaffected). When present, the write is guarded on the stored
@@ -28816,6 +28875,7 @@ components:
- WEB
- TELEGRAM
- DAYLIO
- NOTIFICATION
externalId:
description: "iOS-side source-stable id for idempotent dedup on the `(userId, source, externalId)` key. Must be stable
across app restarts — an object description or memory address (`<Class: 0x…>`, `0x12ab34cd`) is a new value
@@ -29336,6 +29396,7 @@ components:
- WEB
- TELEGRAM
- DAYLIO
- NOTIFICATION
externalId:
type: string
minLength: 1
@@ -52677,6 +52738,19 @@ components:
- nudgeRoutine
- nudgeFrequency
additionalProperties: false
content:
type: object
properties:
detail:
type: string
enum:
- generic
- detailed
description: What a notification may show. "generic" (default) names what it is about with no health figure; "detailed"
adds figures such as the morning score. Tap targets and quick answers are the same in both.
required:
- detail
additionalProperties: false
updatedAt:
description: "Optimistic-concurrency token: the stored row's `updatedAt` at read/write time. Echo it back as
`baseUpdatedAt` on the next write. Opaque — only ever echo a server-returned value, never parse or
@@ -52689,6 +52763,7 @@ components:
- mood
- cycle
- coach
- content
additionalProperties: false
PatchNotificationPrefsResponse:
type: object
@@ -65116,6 +65191,7 @@ components:
- WEB
- TELEGRAM
- DAYLIO
- NOTIFICATION
externalId:
anyOf:
- type: string
@@ -78271,6 +78347,42 @@ components:
required:
- ok
additionalProperties: false
NotificationActionResponse:
type: object
properties:
data:
$ref: "#/components/schemas/NotificationActionResult"
error:
type: "null"
meta:
type: object
properties:
requestId:
type: string
additionalProperties: false
required:
- data
- error
additionalProperties: false
NotificationActionResult:
type: object
properties:
logged:
type: boolean
const: true
action:
type: string
enum:
- mood-good
- mood-okay
- mood-bad
description: "The answer that was logged: mood-good = 4 (GUT), mood-okay = 3 (OKAY), mood-bad = 2 (SCHLECHT) on the
five-point mood scale."
required:
- logged
- action
additionalProperties: false
description: A quick answer from a notification, logged as a mood entry.
GetNotificationPreferences:
type: object
properties:
+89
View File
@@ -234,6 +234,8 @@ choice existed keeps sending:
message are masked as they are on every other channel.
- `priority` is a word: `urgent` for an event flagged urgent, `high` for
medication reminders, `default` for everything else.
- `url`, when `APP_URL` is set, is the page the notification leads to (see
[Tap targets](#what-tapping-a-notification-opens)). Absent otherwise.
**Gotify** sends the body Gotify's `POST /message` endpoint expects:
@@ -450,6 +452,93 @@ Two gotchas worth knowing before you blame a stale token:
> in the web UI. If you only run the PWA, ignore it entirely — your
> medication reminders come from the server cron over the channels above.
## Tap targets, content and quick answers
### What tapping a notification opens
Every notification leads somewhere in the app. The server decides where,
once per event type, and every channel carries the same target:
| Notification | Opens |
| -------------------------------------------- | ---------------------------------------------------------------------------------- |
| Mood reminder | `/mood`, with the mood entry sheet already open |
| Morning briefing | the dashboard |
| Medication reminder, low supply, shared dose | `/medications` (low supply opens the medication) |
| Check-up and measurement reminders | `/checkups` |
| Proactive Coach nudge | the Coach conversation it started |
| Cycle reminders | `/cycle` (nothing with discreet notifications on) |
| New sign-in | Settings, Security |
| Integration sync failing | Settings, Integrations (an admin alert about another account opens the admin page) |
| Illness red flag | the illness episode |
| Other system alerts | the dashboard, or the admin status page for operator alerts |
How each channel carries it:
- **ntfy**: the `Click` header, so tapping the notification opens the page.
- **Telegram**: an **Open in HealthLog** button under the message, below any
action buttons. Telegram only accepts `https` button links on a public
host, so a plain-HTTP instance gets a text link instead, and an instance
on `localhost` gets no link.
- **Web Push**: the service worker opens the page, or focuses an open
HealthLog tab and navigates it there.
- **APNs**: the path rides the payload as `url`.
- **Webhook**: the generic body gains a `url` field; the Gotify body gains
`extras["client::notification"].click.url`, which the Gotify app opens.
- **Email**: a link line under the message.
ntfy, Telegram, the webhook and email need an absolute link, built from
`APP_URL` (or `NEXT_PUBLIC_APP_URL`). Without one those channels deliver as
before, just without a link. A notification about a profile you look after
as a Guardian carries no deep link, because your session opens on your own
record.
### Health figures in notifications
Settings, Notifications, **Health figures in notifications** decides what a
notification may say on a lock screen:
- **Off** (the default): a notification says what it is about and shows no
health figure. The morning briefing reads "Your morning briefing".
- **On**: notifications add their figures. The morning briefing becomes
"Morning score 78" with the day's one-line summary underneath.
Tap targets and quick answers work the same either way. The setting is
stored as `content.detail` (`generic` or `detailed`) in the notification
preferences (`PATCH /api/auth/me/notification-prefs`) and travels with the
account backup.
### Quick answers on the mood reminder
On **ntfy** the mood reminder carries three buttons, **Good**, **Okay** and
**Bad**. Tapping one logs a mood entry straight from the notification,
without opening the app, and clears the notification. They map onto the
five-point mood scale as Good = 4, Okay = 3, Bad = 2; the outer points
stay in the app. The entry is marked with the source **Notification**.
Each button calls `POST <APP_URL>/api/notifications/action/<token>`. The
token is the only credential, so it is built to be harmless on its own:
- it is signed with `API_TOKEN_HMAC_KEY` and names one account and one
answer, so it cannot be moved to another account or another answer;
- it expires six hours after the reminder was sent;
- the three answers of one reminder are one use between them: the first
tap logs, every later tap on that reminder is refused;
- the route is rate-limited before it reads the token, refuses when the
mood module has been turned off, and the token is scrubbed from logs.
The buttons need `APP_URL`, because the ntfy app calls the URL from your
phone. Your phone has to reach the instance at that address.
**Telegram** keeps its own keyboard on the mood reminder: the full 1 to 5
scale, a note and a "later" button.
**Web Push** offers no buttons. Most browsers show at most two actions,
which cannot carry a three-way answer, and Safari on iPhone shows none.
Tapping the notification opens the mood entry sheet instead.
**APNs**: the iOS app draws its own buttons from the notification category
it registers for the mood reminder.
## Which channel should I pick?
| Your setup | Recommended channel |