Notifications

An in-app inbox with an unread count, email for what was missed, preferences per type and one-click unsubscribe.

This is an app part spec on Spekkr, published by rook. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
rook/notifications
Version
0.1.2
Published by
rook
Updated
15 Nov 2026

Build this spec

Build the spec at https://spekkr.com/rook/notifications/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by rook.

What does the result look like?

Notifications: desk bell panelNotifications: inboxNotifications: preferencesNotifications: unsubscribe

What can I customize?

Database
How the count stays current Asking every 30 seconds, or a connection the server pushes down.

Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.

What do I get?

  • spec.md Requirements and acceptance criteria.

    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.
    # 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.
    

    Open spec.md as plain text

  • design.md Data model, rules and flows.

    Design

    This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them.

    Data model

    Use the database in the database input.

    TableColumns
    notificationsid (grows with time), user_id, type, data (JSON), dedupe_key, created_at, read_at, emailed_at
    notification_preferencesuser_id, type, in_app, email; primary key on the first two
    notification_settingsuser_id (primary key), email_mode (each or daily), time_zone, last_email_at, last_digest_on

    Indexes: user_id, id descending for the inbox; user_id where read_at is null for the count; a unique one on user_id, type, dedupe_key where the key is set.

    A missing preference row means the type's defaults. Rows exist only for what a person changed.

    Rules

    • The cursor is the id of the last notification shown. The next page is everything with a smaller id. Page numbers skip or repeat rows when new ones arrive.
    • "Mark all as read" sends the id of the newest notification the page knows about, and the server marks only those at or below it.
    • For the 24 hours in R1, a job clears dedupe_key on notifications 24 hours old or older, which frees the unique index.
    • Titles are made when a notification is shown, from type and data, so a change of wording applies to old notifications too. Escape everything taken from data.

    Email

    A job runs every minute. For each person with email in mode each, it takes the notifications that are unread, not yet emailed, older than email_delay_minutes and of a type whose email is on. If there are any and last_email_at is older than the delay, it sends one email and sets emailed_at on each in the same transaction as last_email_at.

    The daily summary is the same job with another test: the local time in the person's time_zone has passed 08:00 and last_digest_on is before today's local date. Work out local time with the platform's time zone database, never with a fixed offset.

    Put sending behind one small interface so tests capture messages without a network. Use the app_name input as the sender's name and in the subject.

    The unsubscribe token

    payload = user id, a full stop, type
    token   = base64url(payload) + "." + base64url(HMAC-SHA-256(UNSUBSCRIBE_SECRET, payload))

    Compare the signature in constant time. The page reached by GET changes nothing until its button is pressed, because mail scanners follow links.

    Configuration

    SecretPurpose
    DATABASE_URLConnection string for the chosen database.
    EMAIL_API_KEYSends the emails. Optional in development.
    EMAIL_API_URLWhere send_email posts each message. Optional in development.
    EMAIL_FROMThe address every email is sent from. Optional in development.
    UNSUBSCRIBE_SECRETSigns unsubscribe links. At least 32 random bytes.

    Who is signed in

    The spec reaches the app's sign-in through one function, current_user(request). It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session.

    When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production.

    Sending email

    Send every email through one function, send_email(to, subject, text).

    • With EMAIL_API_URL and EMAIL_API_KEY set, it makes one POST to EMAIL_API_URL with the header Authorization: Bearer <EMAIL_API_KEY> and the JSON body {"from": EMAIL_FROM, "to": ..., "subject": ..., "text": ...}. Any 2xx answer means sent. The person points the address at their email service, or at a few lines that translate for it.
    • With neither set, outside production, the message goes to a local outbox that tests read. It is not printed: a message can hold a link that signs someone in.

    In production the app refuses to start without both.

    Named here

    • A missing preference row means inbox on and email on.
    • A repeat is blocked until 24 hours have passed. At 24 hours exactly it is created.
    • unread_count is a JSON number.

    What this spec leaves to you

    Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.

    # Design
    
    This file fixes the parts that are easy to get wrong. Choose the language and
    framework that fit the person's project; nothing here depends on them.
    
    ## Data model
    
    Use the database in the `database` input.
    
    | Table | Columns |
    | --- | --- |
    | `notifications` | `id` (grows with time), `user_id`, `type`, `data` (JSON), `dedupe_key`, `created_at`, `read_at`, `emailed_at` |
    | `notification_preferences` | `user_id`, `type`, `in_app`, `email`; primary key on the first two |
    | `notification_settings` | `user_id` (primary key), `email_mode` (`each` or `daily`), `time_zone`, `last_email_at`, `last_digest_on` |
    
    Indexes: `user_id`, `id` descending for the inbox; `user_id` where `read_at` is
    null for the count; a unique one on `user_id`, `type`, `dedupe_key` where the key
    is set.
    
    A missing preference row means the type's defaults. Rows exist only for what a
    person changed.
    
    ## Rules
    
    - The cursor is the `id` of the last notification shown. The next page is
      everything with a smaller `id`. Page numbers skip or repeat rows when new ones
      arrive.
    - "Mark all as read" sends the `id` of the newest notification the page knows
      about, and the server marks only those at or below it.
    - For the 24 hours in R1, a job clears `dedupe_key` on notifications 24 hours old
      or older, which frees the unique index.
    - Titles are made when a notification is shown, from `type` and `data`, so a change
      of wording applies to old notifications too. Escape everything taken from `data`.
    
    ## Email
    
    A job runs every minute. For each person with email in mode `each`, it takes the
    notifications that are unread, not yet emailed, older than `email_delay_minutes`
    and of a type whose email is on. If there are any and `last_email_at` is older
    than the delay, it sends one email and sets `emailed_at` on each in the same
    transaction as `last_email_at`.
    
    The daily summary is the same job with another test: the local time in the
    person's `time_zone` has passed 08:00 and `last_digest_on` is before today's local
    date. Work out local time with the platform's time zone database, never with a
    fixed offset.
    
    Put sending behind one small interface so tests capture messages without a
    network. Use the `app_name` input as the sender's name and in the subject.
    
    ## The unsubscribe token
    
    ```
    payload = user id, a full stop, type
    token   = base64url(payload) + "." + base64url(HMAC-SHA-256(UNSUBSCRIBE_SECRET, payload))
    ```
    
    Compare the signature in constant time. The page reached by `GET` changes nothing
    until its button is pressed, because mail scanners follow links.
    
    ## Configuration
    
    | Secret | Purpose |
    | --- | --- |
    | `DATABASE_URL` | Connection string for the chosen database. |
    | `EMAIL_API_KEY` | Sends the emails. Optional in development. |
    | `EMAIL_API_URL` | Where `send_email` posts each message. Optional in development. |
    | `EMAIL_FROM` | The address every email is sent from. Optional in development. |
    | `UNSUBSCRIBE_SECRET` | Signs unsubscribe links. At least 32 random bytes. |
    
    ## Who is signed in
    
    The spec reaches the app's sign-in through one function, `current_user(request)`.
    It answers with the person's id, and says whether they are an administrator where
    this spec asks. In the person's app it reads their session.
    
    When there is no app yet, build this stand-in and nothing more: a page that lists
    two seeded people, one of them an administrator, with a button for each that sets
    a signed cookie naming them. The stand-in refuses to start in production.
    
    ## Sending email
    
    Send every email through one function, `send_email(to, subject, text)`.
    
    - With `EMAIL_API_URL` and `EMAIL_API_KEY` set, it makes one `POST` to
      `EMAIL_API_URL` with the header `Authorization: Bearer <EMAIL_API_KEY>` and the
      JSON body `{"from": EMAIL_FROM, "to": ..., "subject": ..., "text": ...}`. Any
      2xx answer means sent. The person points the address at their email service, or
      at a few lines that translate for it.
    - With neither set, outside production, the message goes to a local outbox that
      tests read. It is not printed: a message can hold a link that signs someone in.
    
    In production the app refuses to start without both.
    
    ## Named here
    
    - A missing preference row means inbox on and email on.
    - A repeat is blocked until 24 hours have passed. At 24 hours exactly it is
      created.
    - `unread_count` is a JSON number.
    
    ## What this spec leaves to you
    
    Where this spec names something, use that name, so that two builds of it agree.
    Where it does not, the choice is yours. List what you chose in the README.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    Tasks

    Work in order. Finish a task's check before starting the next.

    1. Set up. Add the tables and indexes in design.md, and a clock that tests can set. If there is no app yet, build the smallest one: a signed-in user. Check: migrations run from empty.
    2. Send (R1). The list of types and notify. Check: the R1 acceptance tests pass.
    3. Inbox and count (R2, R3). Check: the R2 and R3 acceptance tests pass.
    4. Preferences (R6). Check: the R6 acceptance tests pass.
    5. Email (R5). Only if email_channel is on. Use the email_delay_minutes and app_name inputs. Check: the R5 acceptance tests pass with email captured in memory.
    6. Unsubscribe (R7). Only if email_channel is on. Check: the R7 acceptance tests pass.
    7. Daily summary (R8). Only if daily_digest is on. Check: the R8 acceptance tests pass.
    8. Keeping the count current (R4). As the live_updates input says. Check: the R4 acceptance test passes.
    9. Clean up (R9) and pages (R10). Check: the R9 test passes, and every page can be used with a keyboard alone and at 360 pixels wide.
    10. Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in spec.md is true.
    # Tasks
    
    Work in order. Finish a task's check before starting the next.
    
    1. **Set up.** Add the tables and indexes in `design.md`, and a clock that tests
       can set. If there is no app yet, build the smallest one: a signed-in user.
       Check: migrations run from empty.
    
    2. **Send (R1).** The list of types and `notify`.
       Check: the R1 acceptance tests pass.
    
    3. **Inbox and count (R2, R3).**
       Check: the R2 and R3 acceptance tests pass.
    
    4. **Preferences (R6).**
       Check: the R6 acceptance tests pass.
    
    5. **Email (R5).** Only if `email_channel` is on. Use the `email_delay_minutes`
       and `app_name` inputs.
       Check: the R5 acceptance tests pass with email captured in memory.
    
    6. **Unsubscribe (R7).** Only if `email_channel` is on.
       Check: the R7 acceptance tests pass.
    
    7. **Daily summary (R8).** Only if `daily_digest` is on.
       Check: the R8 acceptance tests pass.
    
    8. **Keeping the count current (R4).** As the `live_updates` input says.
       Check: the R4 acceptance test passes.
    
    9. **Clean up (R9) and pages (R10).**
       Check: the R9 test passes, and every page can be used with a keyboard alone and
       at 360 pixels wide.
    
    10. **Finish.** Write the README and run the whole test suite.
        Check: every item under "Definition of done" in `spec.md` is true.
    

    Open tasks.md as plain text

Is it for me?

Platforms
web, backend

What does it need?

Accounts
An email-sending service, if email is on
Agent permissions
shell, network
Secrets it reads
DATABASE_URL EMAIL_API_KEY UNSUBSCRIBE_SECRET

What changed?

  • 0.1.215 Nov 2026Names what it builds.
  • 0.1.114 Nov 2026Says "person" where it said "buyer".
  • 0.1.014 Nov 2026Moved from dwrtz/notifications.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.