# Feature: Notify parents of child activity requiring attention ## Overview **Goal:** Alert parents in real-time when a child performs an action that requires their attention (completing a chore, or requesting an affordable reward), even when the parent does not have the app open in an active browser tab. Additionally, send a nightly email digest at 9 pm in the parent's local timezone summarising all still-unacknowledged items. **User Story:** As a parent, I want to receive a notification when: - My child completes a chore so I can review and approve or reject it promptly. - My child requests a reward they can afford so I can review and grant or deny it promptly. I should receive these notifications without needing to have the app open. Additionally, if any items are still unacknowledged at the end of the day, I want to receive a nightly summary email at 9 pm (my local time) that lists each pending chore and reward request with action links so I can approve or deny each item directly from the email without opening the app. **Rules:** - Follow `.github/copilot-instructions.md` - Notifications must be user-opt-in (browser permission request) - Every backend mutation must fire an SSE event (existing requirement) - Web Push is the primary notification channel; in-app SSE toast remains the secondary channel - Do not send email per event — email is reserved for account-level actions - A reward request notification is only sent when the child has enough points to afford the reward; do not notify for requests the child cannot afford - Tapping a notification must open (or focus) the app and navigate directly to the relevant child's `ParentView`, scrolling the pending item card into view within the corresponding section - Each notification must include an **Approve** and **Deny** action button so the parent can act directly from the OS notification tray without opening the app - Action button API calls from the Service Worker use short-lived signed action tokens (same `DigestActionToken` mechanism used for email digest links); tokens are generated server-side when the push payload is built and embedded in the push `data` — the SW never needs cookie access - Browsers that do not support notification `actions` (e.g. iOS Safari) fall back gracefully: tapping the notification body still opens the app as normal - The nightly digest email is sent at 9 pm in the parent's local timezone regardless of whether they have push notifications enabled - The digest is only sent if there is at least one unacknowledged pending item at send time - Approve/deny links in the email are protected by short-lived signed action tokens (valid for 24 hours); they do not rely on browser cookies - Action tokens must encode the `user_id`, `child_id`, `entity_id`, `entity_type`, and `action` and be signed with a server secret using HMAC-SHA256 - Action tokens are single-use: once redeemed the backend marks them consumed so they cannot be replayed --- ## Data Model Changes ### Backend Model New model: `PushSubscription` - `id: str` — unique ID - `user_id: str` — the parent user this subscription belongs to - `endpoint: str` — browser-provided push endpoint URL - `keys: dict` — `{ p256dh: str, auth: str }` from the browser `PushSubscription` - `created_at: str` — ISO timestamp A user may have **multiple** `PushSubscription` records (one per device/browser). The `user_id` + `endpoint` pair is the unique key; re-posting the same endpoint updates the existing record rather than creating a duplicate. Existing model change: `User` — add two fields: - `timezone: str | None` — IANA timezone string (e.g. `"America/New_York"`), updated whenever the frontend posts a push subscription. Used by the digest scheduler to determine the parent's local 9 pm. Defaults to `None` (falls back to UTC). - `email_digest_enabled: bool` — whether the user receives the nightly digest email. Defaults to `True`. Toggled via the User Profile page or via the digest email unsubscribe link. New model: `DigestActionToken` - `id: str` — unique token ID (also used as the URL token) - `user_id: str` - `child_id: str` - `entity_id: str` - `entity_type: str` — `"chore"` or `"reward"` - `action: str` — `"approve"` or `"deny"` - `expires_at: str` — ISO timestamp (24 hours from creation) - `used: bool` — set to `True` once redeemed - `signature: str` — HMAC-SHA256 of the above fields, keyed by `DIGEST_TOKEN_SECRET` env var ### Frontend Model ```ts interface PushSubscription { id: string; user_id: string; endpoint: string; keys: { p256dh: string; auth: string; }; created_at: string; } ``` Existing interface change: `User` — add: ```ts timezone: string | null; email_digest_enabled: boolean; ``` --- ## Backend Implementation 1. Add `pywebpush` and `py-vapid` to `requirements.txt`. 2. Generate a VAPID key pair and store the public/private keys in environment config. 3. New API file: `api/push_subscription_api.py` - `POST /push-subscription` — **upsert**: if a record with matching `user_id` + `endpoint` already exists, update its `keys`; otherwise insert a new `PushSubscription`. Also update `User.timezone` with the submitted IANA timezone string. - `DELETE /push-subscription` — accepts `{ endpoint }` in the request body and removes only that specific subscription for the authenticated user (not all subscriptions). 4. New DB helper: `db/push_subscriptions.py` — CRUD for `PushSubscription` records. Must support multiple records per user. Key methods: `get_subscriptions_by_user(user_id)` (returns a list), `upsert_subscription(user_id, endpoint, keys)`, `delete_by_endpoint(user_id, endpoint)`. 5. **Prerequisite — duplicate reward request guard:** In `request_reward()` in `child_api.py`, before creating a new `PendingConfirmation`, check whether one already exists for the same `child_id`, `entity_id` (`reward_id`), and `entity_type='reward'` with `status='pending'`. If so, return a `409 Conflict` with error code `DUPLICATE_REWARD_REQUEST`. This prevents the same reward from being requested twice. 6. In the chore confirmation flow (where `send_event_for_current_user` is called for a completed/pending chore), also look up **all** of the parent's stored `PushSubscription` records and fire a web push to each. The push payload must contain: `user_id`, child name, chore name, `child_id`, `entity_id` (task ID), `entity_type: "chore"`, plus `approve_token` and `deny_token` (two freshly generated `DigestActionToken` IDs for the approve and deny actions). The frontend/SW will use these to construct the deep link `/parent/?scrollTo=&entityType=chore`. 7. In the reward request flow (`child_reward_request` with operation `REQUEST_CREATED`), check whether the child's current point balance is >= the reward's cost. If so, look up **all** of the parent's stored `PushSubscription` records and fire a web push to each. The push payload must contain: `user_id`, child name, reward name, reward cost, `child_id`, `entity_id` (reward ID), `entity_type: "reward"`, plus `approve_token` and `deny_token`. The frontend/SW constructs the deep link `/parent/?scrollTo=&entityType=reward`. If the child cannot afford the reward, skip the push notification. 8. Add a new endpoint `POST /child//deny-reward-request` (with body `{ reward_id }`) that a parent can call to reject a child's pending reward request. It should remove the `PendingConfirmation` record, fire a `CHILD_REWARD_REQUEST` SSE event with operation `REQUEST_CANCELLED`, and create a tracking event with action `denied`. This is the parent-facing counterpart to the child's `cancel-request-reward`. **Graceful handling:** If no pending request exists (e.g. the reward was already granted or cancelled), return `200` with `{ "message": "This reward request has already been resolved." }` instead of a 404. 9. New utility: `utils/email_digest_scheduler.py` - Uses `APScheduler` (already in use for the account deletion scheduler — follow the same pattern) with a `BackgroundScheduler`. - **Important:** The scheduler job function must run inside `with app.app_context():` to access Flask extensions (Flask-Mail, config, TinyDB). Pass the Flask `app` instance to the scheduler setup function, and use `app.app_context()` as a context manager wrapping the job body. - Runs a job **every hour** on the server. Each run inspects all users where `user.verified == True` and `user.email_digest_enabled == True`. For each matching user, derive their current local hour from `User.timezone` (falling back to UTC if `timezone` is `None`), and send the digest to any user whose local hour is `21` (9 pm) and who has at least one pending `PendingConfirmation`. - For each pending item, generate a `DigestActionToken` for both `approve` and `deny` actions and persist them in TinyDB. - Call `send_digest_email()` (see step 10) with the assembled item list. - Skip sending if `DB_ENV == 'e2e'`. 10. New function `send_digest_email(to_email, items)` in `utils/email_sender.py`. Each item in `items` is a dict with keys: `child_name`, `entity_name`, `entity_type`, `view_url`, `approve_token`, `deny_token`. The HTML email body must: - Open with a branded header ("Reward App — Daily Summary"). - Contain one section per child, listing that child's pending items. - For each item show the item name and three links side by side: - **View** — deep link to `/parent/?scrollTo=&entityType=` - **Approve** — `/api/digest-action/` - **Deny** — `/api/digest-action/` - Use inline CSS styles consistent with the existing `send_pin_setup_email` format (no external stylesheets). Approve link styled green, Deny link styled red. - Close with a footer containing an unsubscribe link: "You are receiving this because you have the Reward App. [Unsubscribe from daily digest](/api/digest-unsubscribe/)." The `unsubscribe_token` is a signed HMAC token encoding the `user_id` with a 30-day expiry. 11. New API endpoint `GET /digest-action/` in `api/digest_action_api.py`: - Validates the token exists in TinyDB, has not expired, has not been used, and the HMAC signature is valid. - If invalid/expired: return a plain 400 HTML error page (no redirect). - If valid: mark the token `used = True`, then: - `approve` + `chore` → call the same logic as `approve-chore` - `deny` + `chore` → call the same logic as `reject-chore` - `approve` + `reward` → call the same logic as `trigger-reward` - `deny` + `reward` → call the same logic as `deny-reward-request` - On success: **302 redirect** to `/parent/?scrollTo=&entityType=` so the parent lands on the correct view. - This endpoint is **unauthenticated** — the signed token is the credential. 12. New API endpoint `GET /digest-unsubscribe/` in `api/digest_action_api.py`: - Validates the unsubscribe token signature and 30-day expiry. - If valid: sets `User.email_digest_enabled = False` and returns a simple HTML confirmation page: "You have been unsubscribed from daily digest emails. To re-enable, visit your profile in the app." - If invalid/expired: returns a plain 400 HTML error page. 13. Add `DIGEST_TOKEN_SECRET` to environment config. Document it in the README. 14. Extend `PUT /user/profile` in `api/user_api.py` to also accept an optional `email_digest_enabled: bool` field in the request body. When present, update `User.email_digest_enabled`. Include `email_digest_enabled` in the `GET /user/profile` response. 15. Register the new blueprints and start the digest scheduler in `main.py`. ## Backend Tests - [x] `POST /push-subscription` saves a subscription for the current user - [x] `POST /push-subscription` upserts when the same endpoint is posted again (updates keys, no duplicate) - [x] `POST /push-subscription` supports multiple endpoints per user (one per device) - [x] `POST /push-subscription` updates `User.timezone` with the submitted IANA timezone string - [x] `POST /push-subscription` rejects unauthenticated requests - [x] `DELETE /push-subscription` removes only the specified endpoint for the current user - [x] Web push is fired to all stored subscriptions when a chore is marked complete - [x] Web push payload includes `user_id`, `approve_token`, and `deny_token` - [x] Web push is not fired when the parent has no stored subscription (no error raised) - [x] Web push is fired when a child requests a reward they can afford and the parent has a stored subscription - [x] Web push is NOT fired when a child requests a reward they cannot afford - [x] Web push is not fired for reward requests when the parent has no stored subscription (no error raised) - [x] `request_reward()` returns 409 Conflict for duplicate pending reward requests - [x] `POST /child//deny-reward-request` removes the pending confirmation and fires the `REQUEST_CANCELLED` SSE event - [x] `POST /child//deny-reward-request` returns 200 with message when reward already resolved (no pending request) - [x] `POST /child//deny-reward-request` rejects unauthenticated requests - [x] Digest scheduler identifies verified, digest-enabled users whose local time is 9 pm and who have pending items - [x] Digest scheduler skips users with no pending items - [x] Digest scheduler skips unverified users - [x] Digest scheduler skips users with `email_digest_enabled == False` - [x] Digest scheduler reads timezone from `User.timezone`, falling back to UTC - [x] Digest scheduler skips sending when `DB_ENV == 'e2e'` - [x] `DigestActionToken` is created with correct fields, expiry, and valid HMAC signature - [x] `GET /digest-action/` executes the correct backend action for each combination of `entity_type` × `action` - [x] `GET /digest-action/` redirects to the correct deep-link URL on success - [x] `GET /digest-action/` returns 400 for expired tokens - [x] `GET /digest-action/` returns 400 for already-used tokens - [x] `GET /digest-action/` returns 400 for tampered/invalid signatures - [x] Digest email HTML contains per-child sections, item names, View / Approve / Deny links, and unsubscribe link - [x] `GET /digest-unsubscribe/` sets `email_digest_enabled = False` and returns confirmation HTML - [x] `GET /digest-unsubscribe/` returns 400 for expired or invalid tokens - [x] `GET /user/profile` response includes `email_digest_enabled` - [x] `PUT /user/profile` with `email_digest_enabled: false` updates the user and disables digest - [x] `PUT /user/profile` with `email_digest_enabled: true` re-enables digest --- ## Frontend Implementation 1. **PWA manifest:** Create `public/manifest.json` with `name`, `short_name`, `start_url: "/"`, `display: "standalone"`, `theme_color`, `background_color`, and an `icons` array. Add `` to `index.html`. This is required for iOS "Add to Home Screen" and for push notifications on iOS Safari. 2. Register a Service Worker (`public/sw.js`) that listens for the `push` event and calls `self.registration.showNotification(...)` with: - `title`, `body`, and a `data` object containing `child_id`, `entity_id`, `entity_type`, `approve_token`, and `deny_token` - An `actions` array: `[{ action: 'approve', title: 'Approve' }, { action: 'deny', title: 'Deny' }]` - Note: the `actions` field is silently ignored by browsers that do not support it (e.g. iOS Safari); the notification body tap still works normally. 3. On parent mount (e.g., `ParentLayout.vue` or `App.vue`), request notification permission and, if granted, retrieve the `PushSubscription` from the browser and `POST` it to `/api/push-subscription`, including the user's IANA timezone string: `Intl.DateTimeFormat().resolvedOptions().timeZone`. 4. Clean up: if permission is denied or revoked, call `DELETE /api/push-subscription` with `{ endpoint }` in the body to remove that specific subscription. 5. The Service Worker's `notificationclick` handler must: - Close the notification with `event.notification.close()` - If `event.action === 'approve'`: `fetch('/api/digest-action/')` (GET, no credentials needed — the signed token IS the credential). - If `event.action === 'deny'`: `fetch('/api/digest-action/')` (GET, no credentials needed). - If no action (body tap): construct the deep-link URL `/parent/?scrollTo=&entityType=`, check `clients.matchAll({ type: 'window' })` for an existing open window on the same origin — if found, call `client.focus()` and `client.navigate(url)`; otherwise call `clients.openWindow(url)`. 6. `ParentView` uses vertically stacked `ScrollingList` sections (not tabs). The existing `scrollTo` + `entityType` query params call `scrollToItem()` on the correct list ref, which scrolls the card into view and centers it. After scrolling, apply a temporary pulse/highlight CSS animation (e.g. a 2-second `@keyframes highlight-pulse` using `--item-card-ready-shadow` or `--accent`) to draw the parent's eye to the target card. The animation class should be removed after it completes. 7. **Parent mode timeout — return URL:** When the router guard redirects a non-parent-authenticated user away from a `/parent/...` deep link (e.g. from a notification body tap or email digest redirect), it saves the intended URL to `localStorage['parentReturnUrl']`. `LoginButton` checks for a pending return URL on mount and auto-opens the PIN modal. On successful PIN entry, `consumePendingReturnUrl()` is called and the user is redirected to the saved deep link instead of the default `/parent`. If the parent cancels the PIN modal, `clearPendingReturnUrl()` removes the saved URL so the prompt does not re-appear. The URL is validated to start with `/parent` before saving to prevent open redirect. 8. Existing SSE in-app toast/badge behavior is unchanged — it remains the secondary channel when the tab is active. 9. On `UserProfile.vue`, add an "Email Digest" toggle below the existing action buttons. When toggled, call `PUT /api/user/profile` with `{ email_digest_enabled: }`. Initialize the toggle state from the `GET /api/user/profile` response (which now includes `email_digest_enabled`). ## Frontend Tests - [ ] Parent sees a browser notification when a chore is completed and the tab is backgrounded - [ ] Chore notification includes "Approve" and "Deny" action buttons (on supporting browsers) - [ ] Clicking "Approve" on a chore notification uses the signed action token URL (not cookie-authenticated fetch) - [ ] Clicking "Deny" on a chore notification uses the signed action token URL and dismisses the notification without opening the app - [ ] Tapping the chore notification body opens the app, scrolls to the pending chore within the tasks section of `ParentView` - [x] Scrolled-to card receives a temporary highlight/pulse animation - [ ] Parent sees a browser notification when a child requests an affordable reward and the tab is backgrounded - [ ] Reward notification includes "Approve" and "Deny" action buttons (on supporting browsers) - [ ] Clicking "Approve" on a reward notification uses the signed action token URL and dismisses the notification without opening the app - [ ] Clicking "Deny" on a reward notification uses the signed action token URL and dismisses the notification without opening the app - [ ] Tapping the reward notification body opens the app, scrolls to the pending reward within the rewards section of `ParentView` - [ ] If the app is already open in another tab, tapping the notification body focuses that tab and navigates it (no duplicate window opened) - [ ] No browser notification is shown for a reward request the child cannot afford - [x] Notification permission is requested on parent login/mount - [x] If permission is denied, no subscription is posted to the backend - [x] Push subscription `POST` body includes the browser's IANA timezone string - [x] User Profile page shows an "Email Digest" toggle - [x] Toggling Email Digest off calls `PUT /api/user/profile` with `email_digest_enabled: false` - [x] Toggling Email Digest on calls `PUT /api/user/profile` with `email_digest_enabled: true` --- ## Future Considerations - **iOS PWA caveat**: Web Push on iOS Safari requires the user to have added the app to their Home Screen (PWA mode). Until then, the in-app SSE toast is the only delivery mechanism for iOS Safari users in a regular browser tab. Consider prompting parents to install the PWA. Note that notification `actions` buttons are also not supported on iOS Safari — the body-tap deep-link is the only interaction available on that platform. - **Notification preferences**: Allow parents to toggle specific notification types (chore complete, reward request, etc.) per child. - **Configurable digest time**: Allow the parent to choose what time the daily digest is sent (default 9 pm). --- ## E2E Test Plan A full Playwright E2E test plan has been produced and saved to: `frontend/vue-app/e2e/plans/parent-notifications.plan.md` The plan covers 9 scenario groups (41 automated test cases + 1 manual QA checklist): | # | Group | Cases | | --- | ----------------------------------------- | ----- | | 1 | Push subscription registration | 5 | | 2 | Chore notification — approve flow | 8 | | 3 | Chore notification — reject flow | 5 | | 4 | Reward notification — grant flow | 7 | | 5 | Reward notification — deny flow | 6 | | 6 | ParentView deep-link navigation | 7 | | 7 | Digest action token — happy paths | 8 | | 8 | Digest action token — error paths | 5 | | 9 | Service Worker push — manual QA checklist | — | **Prerequisite noted in plan:** A backend test-only endpoint `POST /api/admin/test/digest-token` (active only when `DB_ENV=e2e`) is required before scenario groups 7 and 8 can run. --- ## Acceptance Criteria (Definition of Done) ### Backend - [x] `PushSubscription` model and DB helper exist and follow existing patterns; supports multiple subscriptions per user (one per device) - [x] `POST /push-subscription` upserts by `user_id` + `endpoint` and also updates `User.timezone` - [x] `DELETE /push-subscription` removes only the specified endpoint for the authenticated user - [x] Web push is sent to **all** stored subscriptions when a child completes a chore - [x] Web push is sent to **all** stored subscriptions when a child requests an affordable reward - [x] Web push payload includes `user_id`, `approve_token`, and `deny_token` - [x] Web push is NOT sent when the child cannot afford the requested reward - [x] `request_reward()` rejects duplicate pending reward requests with 409 Conflict - [x] `POST /child//deny-reward-request` endpoint is implemented, authenticated, fires the correct SSE event, and creates a tracking event - [x] `POST /child//deny-reward-request` returns 200 with message when reward already resolved - [x] `utils/email_digest_scheduler.py` is implemented using APScheduler, runs hourly, uses `with app.app_context():`, and sends digests at 9 pm local time - [x] Digest scheduler reads timezone from `User.timezone` (falling back to UTC) and only processes verified users with `email_digest_enabled == True` - [x] `send_digest_email()` produces a well-formatted HTML email with per-child sections, View / Approve / Deny links, and an unsubscribe link - [x] `GET /digest-action/` validates the token and performs the correct action - [x] `DigestActionToken` is single-use: redeeming it marks it consumed and subsequent requests with the same token return 400 - [x] `GET /digest-unsubscribe/` sets `email_digest_enabled = False` and returns confirmation HTML - [x] `GET /user/profile` includes `email_digest_enabled`; `PUT /user/profile` accepts `email_digest_enabled` toggle - [x] `DIGEST_TOKEN_SECRET` and VAPID keys are configurable via environment variables (not hardcoded) - [x] All backend tests pass ### Frontend - [x] PWA manifest (`public/manifest.json`) is present and linked in `index.html` - [x] Service Worker is registered and handles `push` and `notificationclick` events - [x] Parent is prompted for notification permission on mount - [x] Subscription is posted to the backend on permission grant and removed on revoke/deny - [ ] Native notification appears when a chore is completed with the tab backgrounded, with "Approve" and "Deny" action buttons - [ ] Native notification appears when a child requests an affordable reward with the tab backgrounded, with "Approve" and "Deny" action buttons - [ ] No native notification appears for a reward request the child cannot afford - [ ] Clicking "Approve" on a chore notification uses the signed action token (no cookie auth) without opening the app - [ ] Clicking "Deny" on a chore notification uses the signed action token without opening the app - [ ] Clicking "Approve" on a reward notification uses the signed action token without opening the app - [ ] Clicking "Deny" on a reward notification uses the signed action token without opening the app - [ ] Tapping a chore notification body opens (or focuses) the app and scrolls to the pending chore within the tasks section - [ ] Tapping a reward notification body opens (or focuses) the app and scrolls to the pending reward within the rewards section - [x] Scrolled-to card receives a temporary highlight/pulse animation - [ ] If the app is already open, the existing tab is focused and navigated rather than opening a new window - [ ] In-app SSE toast behavior is unchanged - [x] Push subscription registration includes the browser's IANA timezone - [x] User Profile page includes an "Email Digest" toggle that calls `PUT /api/user/profile` with `email_digest_enabled` - [x] When a deep-link `/parent/...` is blocked by an expired parent session, the intended URL is saved to `localStorage` and the PIN modal is auto-opened; on successful PIN entry the parent is redirected to the saved URL - [x] Cancelling the PIN modal clears the saved return URL (no repeat prompt) - [ ] All frontend tests pass ### Email Digest - [x] Digest email is sent at 9 pm in the parent's local timezone when pending items exist - [x] Digest is not sent if there are no pending items - [x] Email contains one section per child with pending items - [x] Each item row shows the item name and three links: View, Approve, Deny - [x] Approve link is visually styled green; Deny link is styled red - [ ] Clicking Approve in the email performs the approve action and redirects to the correct `ParentView` deep link - [ ] Clicking Deny in the email performs the deny action and redirects to the correct `ParentView` deep link - [ ] Clicking View in the email opens the app to the correct `ParentView` deep link - [x] Action tokens expire after 24 hours and return a 400 error page when used after expiry - [x] Action tokens are single-use: a second click on the same link returns a 400 error page - [x] Digest email includes an unsubscribe link in the footer - [x] Unsubscribe link sets `email_digest_enabled = False` and shows a confirmation page - [x] Digest is not sent to unverified users - [x] Digest is not sent to users who have unsubscribed (`email_digest_enabled == False`) - [x] Digest is not sent in `e2e` test environment --- ## Test Run Results **Date:** Implementation complete **Backend tests run:** `pytest tests/test_push_subscription_api.py tests/test_digest_token.py tests/test_digest_action_api.py -v` **Results:** 36 passed, 0 failed **Full suite:** `pytest tests/ -v` → 340 passed, 0 failed (no regressions) **New test files:** - `backend/tests/test_push_subscription_api.py` — 13 tests covering VAPID key endpoint, subscribe, upsert, timezone update, auth guard, unsubscribe - `backend/tests/test_digest_token.py` — 12 tests covering token creation, validate/consume, expiry, tampered signature, unsubscribe token lifecycle - `backend/tests/test_digest_action_api.py` — 11 tests covering approve/deny chore/reward, 302 redirect, invalid/used token 400, unsubscribe endpoint - `backend/tests/test_web_push.py` — 6 tests covering push firing on chore confirm and reward request, payload fields, no-subscription no-error - `backend/tests/test_digest_scheduler.py` — 15 tests covering scheduler eligibility logic, e2e skip, timezone fallback, email HTML content (child sections, item names, View/Approve/Deny, unsubscribe, color styling)