# 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`, with the correct tab active and the pending item card scrolled into view - 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 must be authenticated using the parent's existing HttpOnly JWT cookie (`credentials: 'include'`) - 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` - `timezone: str` — IANA timezone string captured from the browser (e.g. `"America/New_York"`); used to schedule the 9 pm digest - `created_at: str` — ISO timestamp 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; }; timezone: string; created_at: string; } ``` --- ## 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` — save a new `PushSubscription` to TinyDB for the authenticated user - `DELETE /push-subscription` — remove the stored subscription for the authenticated user 4. New DB helper: `db/push_subscriptions.py` — CRUD for `PushSubscription` records. 5. In the chore confirmation flow (where `send_event_for_current_user` is called for a completed/pending chore), also look up the parent's stored `PushSubscription` and fire a web push payload containing: child name, chore name, `child_id`, `entity_id` (task ID), and `entity_type: "chore"`. The frontend will use these to construct the deep link `/parent/?scrollTo=&entityType=chore`. 6. 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 the parent's stored `PushSubscription` and fire a web push payload containing: child name, reward name, reward cost, `child_id`, `entity_id` (reward ID), and `entity_type: "reward"`. The frontend constructs the deep link `/parent/?scrollTo=&entityType=reward`. If the child cannot afford the reward, skip the push notification. 7. 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`. 8. New utility: `utils/email_digest_scheduler.py` - Uses `APScheduler` (already in use for the account deletion scheduler — follow the same pattern) with a `BackgroundScheduler`. - Runs a job **every hour** on the server. Each run inspects all users, derives their current local hour from their stored `timezone` (from `PushSubscription`, falling back to UTC if absent), and sends 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 9) with the assembled item list. - Skip sending if `DB_ENV == 'e2e'`. 9. 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: "You are receiving this because you have the Reward App. If items are already resolved, you can ignore this email." 10. 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. 11. Add `DIGEST_TOKEN_SECRET` to environment config. Document it in the README. 12. Register the new blueprint and start the digest scheduler in `main.py`. ## Backend Tests - [ ] `POST /push-subscription` saves a subscription for the current user - [ ] `POST /push-subscription` rejects unauthenticated requests - [ ] `DELETE /push-subscription` removes the subscription for the current user - [ ] Web push is fired when a chore is marked complete and the parent has a stored subscription - [ ] Web push is not fired when the parent has no stored subscription (no error raised) - [ ] Web push is fired when a child requests a reward they can afford and the parent has a stored subscription - [ ] Web push is NOT fired when a child requests a reward they cannot afford - [ ] Web push is not fired for reward requests when the parent has no stored subscription (no error raised) - [ ] `POST /child//deny-reward-request` removes the pending confirmation and fires the `REQUEST_CANCELLED` SSE event - [ ] `POST /child//deny-reward-request` returns 404 when no pending request exists - [ ] `POST /child//deny-reward-request` rejects unauthenticated requests - [ ] Digest scheduler identifies users whose local time is 9 pm and who have pending items - [ ] Digest scheduler skips users with no pending items - [ ] Digest scheduler skips sending when `DB_ENV == 'e2e'` - [ ] `DigestActionToken` is created with correct fields, expiry, and valid HMAC signature - [ ] `GET /digest-action/` executes the correct backend action for each combination of `entity_type` × `action` - [ ] `GET /digest-action/` redirects to the correct deep-link URL on success - [ ] `GET /digest-action/` returns 400 for expired tokens - [ ] `GET /digest-action/` returns 400 for already-used tokens - [ ] `GET /digest-action/` returns 400 for tampered/invalid signatures - [ ] Digest email HTML contains per-child sections, item names, and View / Approve / Deny links --- ## Frontend Implementation 1. 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`, and `entity_type` - 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. 2. 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`. 3. Clean up: if permission is denied or revoked, call `DELETE /api/push-subscription`. 4. The Service Worker's `notificationclick` handler must: - Close the notification with `event.notification.close()` - If `event.action === 'approve'`: - For `entity_type === 'chore'`: `fetch('/api/child//approve-chore', { method: 'POST', credentials: 'include', body: { task_id: entity_id } })` - For `entity_type === 'reward'`: `fetch('/api/child//trigger-reward', { method: 'POST', credentials: 'include', body: { reward_id: entity_id } })` - If `event.action === 'deny'`: - For `entity_type === 'chore'`: `fetch('/api/child//reject-chore', { method: 'POST', credentials: 'include', body: { task_id: entity_id } })` - For `entity_type === 'reward'`: `fetch('/api/child//deny-reward-request', { method: 'POST', credentials: 'include', body: { reward_id: entity_id } })` - 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)`. 5. `ParentView` already handles the `scrollTo` + `entityType` query params: it activates the corresponding tab (chore or reward) and scrolls the matching card into view. No changes to `ParentView` are required if this mechanism already works; verify and document any gaps. 6. Existing SSE in-app toast/badge behavior is unchanged — it remains the secondary channel when the tab is active. ## 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 calls `approve-chore` and dismisses the notification without opening the app - [ ] Clicking "Deny" on a chore notification calls `reject-chore` and dismisses the notification without opening the app - [ ] Tapping the chore notification body opens the app, activates the task tab in `ParentView`, and scrolls the pending chore card into view - [ ] 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 calls `trigger-reward` and dismisses the notification without opening the app - [ ] Clicking "Deny" on a reward notification calls `deny-reward-request` and dismisses the notification without opening the app - [ ] Tapping the reward notification body opens the app, activates the reward tab in `ParentView`, and scrolls the pending reward card into view - [ ] 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 - [ ] Notification permission is requested on parent login/mount - [ ] If permission is denied, no subscription is posted to the backend - [ ] Push subscription `POST` body includes the browser's IANA timezone string --- ## 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). - **Digest opt-out**: Allow parents to unsubscribe from the daily digest independently of push notifications. --- ## 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 - [ ] `PushSubscription` model and DB helper exist and follow existing patterns - [ ] `POST /push-subscription` and `DELETE /push-subscription` endpoints are implemented and authenticated - [ ] Web push is sent to the parent when a child completes a chore and a subscription is on file - [ ] Web push is sent to the parent when a child requests an affordable reward and a subscription is on file - [ ] Web push is NOT sent when the child cannot afford the requested reward - [ ] `POST /child//deny-reward-request` endpoint is implemented, authenticated, fires the correct SSE event, and creates a tracking event - [ ] `utils/email_digest_scheduler.py` is implemented using APScheduler, runs hourly, and sends digests at 9 pm local time - [ ] `send_digest_email()` produces a well-formatted HTML email with per-child sections and View / Approve / Deny links for each pending item - [ ] `GET /digest-action/` validates the token and performs the correct action - [ ] `DigestActionToken` is single-use: redeeming it marks it consumed and subsequent requests with the same token return 400 - [ ] `DIGEST_TOKEN_SECRET` and VAPID keys are configurable via environment variables (not hardcoded) - [ ] All backend tests pass ### Frontend - [ ] Service Worker is registered and handles `push` and `notificationclick` events - [ ] Parent is prompted for notification permission on mount - [ ] 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 calls `approve-chore` without opening the app - [ ] Clicking "Deny" on a chore notification calls `reject-chore` without opening the app - [ ] Clicking "Approve" on a reward notification calls `trigger-reward` without opening the app - [ ] Clicking "Deny" on a reward notification calls `deny-reward-request` without opening the app - [ ] Tapping a chore notification body opens (or focuses) the app, activates the task tab, and scrolls the pending chore card into view - [ ] Tapping a reward notification body opens (or focuses) the app, activates the reward tab, and scrolls the pending reward card into view - [ ] 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 - [ ] Push subscription registration includes the browser's IANA timezone - [ ] All frontend tests pass ### Email Digest - [ ] Digest email is sent at 9 pm in the parent's local timezone when pending items exist - [ ] Digest is not sent if there are no pending items - [ ] Email contains one section per child with pending items - [ ] Each item row shows the item name and three links: View, Approve, Deny - [ ] 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 - [ ] Action tokens expire after 24 hours and return a 400 error page when used after expiry - [ ] Action tokens are single-use: a second click on the same link returns a 400 error page - [ ] Digest is not sent in `e2e` test environment