# Notifications ## What this builds A way for an app to tell a person that something happened: an inbox in the app with a count of what is unread, and an email for what they did not see. People choose what they hear about and can stop any email with one click. Read `spekkr.inputs.json` first. `email_channel` decides whether R5 and R7 exist and `daily_digest` whether R8 does. An unread notification is emailed after `email_delay_minutes` minutes. `live_updates` says how the count stays current. Use `app_name` in every email. This spec needs the app to know who is signed in. It does not build sign-in. ## Out of scope - Push notifications to phones and text messages. - Notifications to people who have no account. - Marketing email. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Send a notification - App code calls `notify(user, type, data, options)`. - Types are a fixed list in code. Each has a title written from the data, a link into the app, and whether it is `required`. Start with `comment_added`, `invited_to_workspace` and the required `security_notice`. - With a `dedupe_key`, a second notification of the same type, for the same person, with the same key inside 24 hours is not created. - A notification added inside a database transaction exists exactly when the transaction commits. Accept when: a notification appears in the right person's inbox, a repeat with the same key adds nothing, and an unknown type is an error. ### R2. The inbox - A person sees their notifications newest first, 20 at a time, and loads more with a cursor, not a page number. - Each shows its title, how long ago, and whether it is read. Following its link marks it read. - "Mark all as read" marks everything that existed at the moment of the click. A notification that arrives during the click stays unread. - A person can never read, mark or count another person's notifications. Accept when: the cursor returns every notification exactly once while new ones arrive, and a request for another person's notification gets 404. ### R3. The unread count - `GET /api/notifications/unread_count` answers with a number. The bell shows it, and shows `99+` above 99. - The count comes from one indexed query. It is not a number kept on the side that can drift. Accept when: the count is right after every combination of new, read and mark-all, and the query uses an index with 100,000 notifications in the table. ### R4. Keeping the count current - If `live_updates` is `polling`, the page asks for the count every 30 seconds while its tab is visible and not at all while hidden. - If `live_updates` is `server_sent_events`, the page holds one connection that the server sends the new count down. A person with several tabs open gets it in each. A dropped connection is reopened after a wait that grows up to 30 seconds. Accept when: a new notification changes the bell without a reload, inside 30 seconds for polling and inside 2 seconds for server-sent events. ### R5. Email what was missed Only if `email_channel` is on. - A notification still unread `email_delay_minutes` minutes after it was created is emailed. One read before then is never emailed. - If several are due for one person at once, they go in one email. - A person gets at most one such email every `email_delay_minutes` minutes. Anything that comes due in between waits for the next one. - A `required` type is emailed at once, on its own. Accept when: reading a notification inside the delay prevents its email, five unread ones produce one email that lists five, and a required one is sent at once. ### R6. Preferences - A page lists every type with a switch for the inbox and, if `email_channel` is on, a switch for email. - A `required` type is shown with its switches on and locked. - A notification is not created for a person who has turned its type off in the inbox, and not emailed to one who has turned its email off. Accept when: each switch stops what it names and nothing else, and a required type cannot be turned off through the page or through its API. ### R7. Unsubscribe Only if `email_channel` is on. - Every email ends with a link to turn off email for that type. It works without signing in. Opening it changes nothing: the page names the type and has one button. Pressing the button turns email for that type off and shows what was turned off, with a button to undo. - Every email carries the headers `List-Unsubscribe` and `List-Unsubscribe-Post: List-Unsubscribe=One-Click`. A `POST` to the address in the first turns off email for that type without any page. - The link holds a signed token that names the person and the type. It does not expire. A token that was altered is refused. - Emails of a `required` type have no unsubscribe link and say why. Accept when: a `POST` to the unsubscribe address turns the switch off, a `GET` alone does not, and a changed token is refused. ### R8. Daily summary Only if `daily_digest` is on. - In R6 a person can choose "once a day" for email. They then get one email at 08:00 in their time zone with what was unread from the day before, and none if there was nothing. - `required` types are still emailed at once. Accept when: a person in `Europe/Berlin` and one in `America/Los_Angeles` each get their summary at 08:00 their time, on a day when the clocks change too. ### R9. Clean up - Read notifications are deleted after 90 days and unread ones after 180. Accept when: a clean-up run deletes exactly the notifications that are old enough. ### R10. Pages - A bell with the count, a panel that opens from it with the latest 20, a page with the whole inbox, and the preferences page. - The bell says its count to screen readers, and the panel can be opened, read and closed with a keyboard. Accept when: each page works with a keyboard alone and at a 360 pixel wide screen. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests capture email in memory and set the clock. - A README explains how to add a type, how to send a notification, and how to run the tests.