Push notifications

Push notifications for iOS and Android: device tokens kept clean, quiet hours in each person's time zone and delivery you can trace.

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/push-notifications
Version
0.1.2
Published by
rook
Updated
15 Nov 2026

Build this spec

Build the spec at https://spekkr.com/rook/push-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?

Push notifications: push desk ledgerPush notifications: push desk quiet hoursPush notifications: push desk mobilePush notifications: push desk sign in

What can I customize?

Database
Which phones

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.

    Push notifications

    What this builds

    The server side of push notifications for a mobile app. It keeps track of which phone belongs to whom, sends through Apple's and Google's services, drops phones that are gone, holds what is not urgent until morning where the person is, and keeps a record of what was sent.

    Read spekkr.inputs.json first. targets says which services are built. quiet_hours decides whether R6 exists, between quiet_start and quiet_end. badge_counts decides whether R8 exists.

    The spec builds the server and a short list of what the app itself must do, in design.md. It needs the server to know who is signed in on a phone.

    Out of scope

    • The app's own screens for asking permission.
    • Notifications in a web browser.
    • Pictures and buttons inside a notification.

    Requirements

    Each requirement has an id. Tests name the id they cover.

    R1. Phones
    • The app sends POST /api/devices with its push token, its platform, its version and the phone's time zone, when it starts and when the token changes.
    • A token belongs to one person at a time. When another person signs in on the phone, the token moves to them and the first person stops getting notifications there.
    • Signing out deletes the token.
    • A person has at most 10 phones. An eleventh replaces the one not seen longest.

    Accept when: a token registered by a second person is no longer the first person's, and signing out leaves no row for the token.

    R2. Send
    • App code calls push(user, type, title, body, data, options).
    • A push asked for inside a database transaction is queued exactly when the transaction commits.
    • Types are a list in code. Each says whether it is urgent and what group it is shown under on the phone.
    • A payload is at most 4,000 bytes. A body that would make it larger is cut, at a character and not inside one, and ends with an ellipsis. data is never cut: a data too large is an error at the call.
    • With a collapse_key, a newer push replaces an older one with the same key on the phone instead of adding to it.

    Accept when: a body of 5,000 characters is sent cut and still valid UTF-8, and data of 5,000 bytes is refused at the call.

    R3. Through the services
    • One adapter for each service in targets, behind one interface, with a stand-in for tests.
    • The adapters follow the table in design.md: how to sign in to the service, what to send, and what each answer means.
    • The sign-in to each service is reused until shortly before it runs out, not made anew for every push.

    Accept when: each row of the table of answers in design.md has a test against the stand-in, and 100 pushes make one sign-in to the service.

    R4. Phones that are gone
    • When a service says a token is no longer valid, the token is deleted at once and not tried again.
    • A token the app has not sent again for 270 days is deleted.

    Accept when: after an "unregistered" answer the token is gone and the next push to that person skips it.

    R5. Retry
    • An answer that says "try later" is tried again after 30 seconds, 2 minutes, 10 minutes and 1 hour, or after the time the service names if it names one.
    • A push can have an expiry. One not delivered by then is dropped, and the service is told the same expiry so it does not deliver late either.
    • After the fifth failure a push to that phone is marked failed.

    Accept when: a stand-in that answers "try later" twice and then accepts is called three times, and an expired push is not sent.

    R6. Quiet hours

    Only if quiet_hours is on.

    • A push of a type that is not urgent, made when it is between quiet_start and quiet_end on the phone, is held and sent at quiet_end there.
    • The phone's time zone decides, with its own rules for summer time. Two phones of one person can get the same push at different moments.
    • Urgent types are sent at once.
    • Several pushes held for one phone are all sent at quiet_end, oldest first, at most 5. If more were held, the fifth is replaced by one that says how many more there are.

    Accept when: every row of the table of cases in design.md gives the time listed, including the two nights when the clocks change.

    R7. What each person wants
    • A person can turn each type off. A type that is off is not sent to any of their phones.
    • Types marked as required cannot be turned off.

    Accept when: turning a type off stops it and nothing else.

    R8. Badge

    Only if badge_counts is on.

    • Each push to an iPhone carries the number of that person's unread notifications, counting the one being sent.
    • When the person reads notifications in the app, the app tells the server, and the server sends a silent push that sets the badge to the new number on their other phones.

    Accept when: three pushes carry 1, 2 and 3, and after reading two the next carries 2.

    R9. A record
    • For each push and each phone: the type, the state, the service's id for it, the attempts and the last answer. Not the title or the body.
    • Records are kept 30 days.
    • An administrator can send a test push to their own phones and see its record.

    Accept when: the record of a sent push holds the service's id, and no record holds a title or a body.

    Definition of done

    • Every acceptance check above has an automated test, and all tests pass. Tests use the stand-in services, set the clock, and use no outside network.
    • No log line holds a push token in full, a key or a service account.
    • A README explains how to get the Apple key and the Firebase service account, what the app must do, how to add a type, and how to run the tests.
    # Push notifications
    
    ## What this builds
    
    The server side of push notifications for a mobile app. It keeps track of which
    phone belongs to whom, sends through Apple's and Google's services, drops phones
    that are gone, holds what is not urgent until morning where the person is, and
    keeps a record of what was sent.
    
    Read `spekkr.inputs.json` first. `targets` says which services are built.
    `quiet_hours` decides whether R6 exists, between `quiet_start` and `quiet_end`.
    `badge_counts` decides whether R8 exists.
    
    The spec builds the server and a short list of what the app itself must do, in
    `design.md`. It needs the server to know who is signed in on a phone.
    
    ## Out of scope
    
    - The app's own screens for asking permission.
    - Notifications in a web browser.
    - Pictures and buttons inside a notification.
    
    ## Requirements
    
    Each requirement has an id. Tests name the id they cover.
    
    ### R1. Phones
    
    - The app sends `POST /api/devices` with its push token, its platform, its
      version and the phone's time zone, when it starts and when the token changes.
    - A token belongs to one person at a time. When another person signs in on the
      phone, the token moves to them and the first person stops getting
      notifications there.
    - Signing out deletes the token.
    - A person has at most 10 phones. An eleventh replaces the one not seen longest.
    
    Accept when: a token registered by a second person is no longer the first
    person's, and signing out leaves no row for the token.
    
    ### R2. Send
    
    - App code calls `push(user, type, title, body, data, options)`.
    - A push asked for inside a database transaction is queued exactly when the
      transaction commits.
    - Types are a list in code. Each says whether it is urgent and what group it is
      shown under on the phone.
    - A payload is at most 4,000 bytes. A body that would make it larger is cut, at a
      character and not inside one, and ends with an ellipsis. `data` is never cut: a
      `data` too large is an error at the call.
    - With a `collapse_key`, a newer push replaces an older one with the same key on
      the phone instead of adding to it.
    
    Accept when: a body of 5,000 characters is sent cut and still valid UTF-8, and
    `data` of 5,000 bytes is refused at the call.
    
    ### R3. Through the services
    
    - One adapter for each service in `targets`, behind one interface, with a
      stand-in for tests.
    - The adapters follow the table in `design.md`: how to sign in to the service,
      what to send, and what each answer means.
    - The sign-in to each service is reused until shortly before it runs out, not
      made anew for every push.
    
    Accept when: each row of the table of answers in `design.md` has a test against
    the stand-in, and 100 pushes make one sign-in to the service.
    
    ### R4. Phones that are gone
    
    - When a service says a token is no longer valid, the token is deleted at once
      and not tried again.
    - A token the app has not sent again for 270 days is deleted.
    
    Accept when: after an "unregistered" answer the token is gone and the next push
    to that person skips it.
    
    ### R5. Retry
    
    - An answer that says "try later" is tried again after 30 seconds, 2 minutes, 10
      minutes and 1 hour, or after the time the service names if it names one.
    - A push can have an expiry. One not delivered by then is dropped, and the
      service is told the same expiry so it does not deliver late either.
    - After the fifth failure a push to that phone is marked failed.
    
    Accept when: a stand-in that answers "try later" twice and then accepts is called
    three times, and an expired push is not sent.
    
    ### R6. Quiet hours
    
    Only if `quiet_hours` is on.
    
    - A push of a type that is not urgent, made when it is between `quiet_start` and
      `quiet_end` on the phone, is held and sent at `quiet_end` there.
    - The phone's time zone decides, with its own rules for summer time. Two phones
      of one person can get the same push at different moments.
    - Urgent types are sent at once.
    - Several pushes held for one phone are all sent at `quiet_end`, oldest first, at
      most 5. If more were held, the fifth is replaced by one that says how many
      more there are.
    
    Accept when: every row of the table of cases in `design.md` gives the time
    listed, including the two nights when the clocks change.
    
    ### R7. What each person wants
    
    - A person can turn each type off. A type that is off is not sent to any of
      their phones.
    - Types marked as required cannot be turned off.
    
    Accept when: turning a type off stops it and nothing else.
    
    ### R8. Badge
    
    Only if `badge_counts` is on.
    
    - Each push to an iPhone carries the number of that person's unread
      notifications, counting the one being sent.
    - When the person reads notifications in the app, the app tells the server, and
      the server sends a silent push that sets the badge to the new number on their
      other phones.
    
    Accept when: three pushes carry 1, 2 and 3, and after reading two the next
    carries 2.
    
    ### R9. A record
    
    - For each push and each phone: the type, the state, the service's id for it, the
      attempts and the last answer. Not the title or the body.
    - Records are kept 30 days.
    - An administrator can send a test push to their own phones and see its record.
    
    Accept when: the record of a sent push holds the service's id, and no record
    holds a title or a body.
    
    ## Definition of done
    
    - Every acceptance check above has an automated test, and all tests pass. Tests
      use the stand-in services, set the clock, and use no outside network.
    - No log line holds a push token in full, a key or a service account.
    - A README explains how to get the Apple key and the Firebase service account,
      what the app must do, how to add a type, 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
    devicesid, user_id, platform, token (unique), app_version, time_zone, created_at, last_seen_at
    pushesid, user_id, type, title, body, data (JSON), collapse_key, expires_at, created_at
    push_deliveriesid, push_id, device_id, state, attempts, send_at, provider_id, last_answer
    push_preferencesuser_id, type, enabled; primary key on the first two

    state is one of held, waiting, sent, failed and dropped. title and body are emptied when every delivery of the push has ended.

    The services

    Confirm these in Apple's and Google's documentation before building. They were right when this was written.

    Apple (APNs)Google (FCM)
    Addresshttps://api.push.apple.com/3/device/TOKEN, over HTTP/2https://fcm.googleapis.com/v1/projects/PROJECT/messages:send
    Sign-inA JWT signed with ES256 by the key in APNS_KEY, with the key id in its header and the team id as issuer. Reuse it for 50 minutes.An OAuth access token for the service account in FCM_SERVICE_ACCOUNT. Reuse it until 5 minutes before it runs out.
    Which appHeader apns-topic with APNS_BUNDLE_IDThe project in the address
    KindHeader apns-push-type: alert, or background for a silent pushnotification and data in the message, or data alone for a silent push
    ExpiryHeader apns-expiration, seconds since 1970android.ttl
    ReplaceHeader apns-collapse-idandroid.collapse_key
    UrgentHeader apns-priority 10, otherwise 5android.priority HIGH, otherwise NORMAL

    Use the sandbox address https://api.sandbox.push.apple.com for builds made in development. Take every address from configuration, so tests can point at the stand-in.

    What an answer means

    ServiceAnswerDo
    Apple200Sent. Keep the apns-id header.
    Apple410, or 400 with reason BadDeviceTokenDelete the token.
    Apple400 with reason DeviceTokenNotForTopicDelete the token and log it: the token is for another app.
    Apple403The sign-in is wrong. Make a new one once, then stop and log.
    Apple429, 500, 503Try later.
    Google200Sent. Keep the message name.
    Google404, or error UNREGISTEREDDelete the token.
    Google400 with error INVALID_ARGUMENTMark failed and log. Do not retry.
    Google401Get a new access token once, then stop and log.
    Google429, 500, 503Try later, after Retry-After if it is there.

    Quiet hours

    Work in the phone's time_zone with the platform's time zone database, never with a fixed offset. With quiet hours from 22:00 to 08:00:

    Push made at (UTC)Phone's time zoneLocal timeSent at (UTC)
    2026-01-10T18:00:00ZAsia/Kolkata23:302026-01-11T02:30:00Z
    2026-01-10T18:00:00ZAmerica/New_York13:00at once
    2026-01-11T01:00:00ZAsia/Kolkata06:302026-01-11T02:30:00Z
    2026-03-28T22:30:00ZEurope/Berlin23:302026-03-29T06:00:00Z
    2026-10-24T21:30:00ZEurope/Berlin23:302026-10-25T07:00:00Z

    The last two are the nights the clocks change in Berlin. A fixed offset gets both wrong by an hour.

    The quiet period can cross midnight, as here, or not. A phone with a time zone the database does not know is treated as UTC.

    What the app must do

    1. Ask for permission to notify at a moment that makes sense to the person, not on first launch.
    2. Send the token to POST /api/devices on every launch and whenever the system gives a new one.
    3. Tell the server on sign-out, before the session is dropped.
    4. When a notification is tapped, open the address in its data.link.
    5. When the person reads notifications, call the server so badges on their other phones are set.

    Configuration

    SecretPurpose
    DATABASE_URLConnection string for the chosen database.
    APNS_KEY, APNS_KEY_ID, APNS_TEAM_ID, APNS_BUNDLE_IDApple's push key and what goes with it. Not needed without iOS.
    FCM_SERVICE_ACCOUNTThe Firebase service account, as JSON. Not needed without Android.

    Named here

    • A payload's size is the size of the JSON sent to the push service, without the device token.
    • Quiet hours that start and end at the same time mean no quiet hours.

    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 |
    | --- | --- |
    | `devices` | `id`, `user_id`, `platform`, `token` (unique), `app_version`, `time_zone`, `created_at`, `last_seen_at` |
    | `pushes` | `id`, `user_id`, `type`, `title`, `body`, `data` (JSON), `collapse_key`, `expires_at`, `created_at` |
    | `push_deliveries` | `id`, `push_id`, `device_id`, `state`, `attempts`, `send_at`, `provider_id`, `last_answer` |
    | `push_preferences` | `user_id`, `type`, `enabled`; primary key on the first two |
    
    `state` is one of `held`, `waiting`, `sent`, `failed` and `dropped`. `title` and
    `body` are emptied when every delivery of the push has ended.
    
    ## The services
    
    Confirm these in Apple's and Google's documentation before building. They were
    right when this was written.
    
    | | Apple (APNs) | Google (FCM) |
    | --- | --- | --- |
    | Address | `https://api.push.apple.com/3/device/TOKEN`, over HTTP/2 | `https://fcm.googleapis.com/v1/projects/PROJECT/messages:send` |
    | Sign-in | A JWT signed with ES256 by the key in `APNS_KEY`, with the key id in its header and the team id as issuer. Reuse it for 50 minutes. | An OAuth access token for the service account in `FCM_SERVICE_ACCOUNT`. Reuse it until 5 minutes before it runs out. |
    | Which app | Header `apns-topic` with `APNS_BUNDLE_ID` | The project in the address |
    | Kind | Header `apns-push-type`: `alert`, or `background` for a silent push | `notification` and `data` in the message, or `data` alone for a silent push |
    | Expiry | Header `apns-expiration`, seconds since 1970 | `android.ttl` |
    | Replace | Header `apns-collapse-id` | `android.collapse_key` |
    | Urgent | Header `apns-priority` 10, otherwise 5 | `android.priority` `HIGH`, otherwise `NORMAL` |
    
    Use the sandbox address `https://api.sandbox.push.apple.com` for builds made in
    development. Take every address from configuration, so tests can point at the
    stand-in.
    
    ## What an answer means
    
    | Service | Answer | Do |
    | --- | --- | --- |
    | Apple | 200 | Sent. Keep the `apns-id` header. |
    | Apple | 410, or 400 with reason `BadDeviceToken` | Delete the token. |
    | Apple | 400 with reason `DeviceTokenNotForTopic` | Delete the token and log it: the token is for another app. |
    | Apple | 403 | The sign-in is wrong. Make a new one once, then stop and log. |
    | Apple | 429, 500, 503 | Try later. |
    | Google | 200 | Sent. Keep the message name. |
    | Google | 404, or error `UNREGISTERED` | Delete the token. |
    | Google | 400 with error `INVALID_ARGUMENT` | Mark failed and log. Do not retry. |
    | Google | 401 | Get a new access token once, then stop and log. |
    | Google | 429, 500, 503 | Try later, after `Retry-After` if it is there. |
    
    ## Quiet hours
    
    Work in the phone's `time_zone` with the platform's time zone database, never
    with a fixed offset. With quiet hours from 22:00 to 08:00:
    
    | Push made at (UTC) | Phone's time zone | Local time | Sent at (UTC) |
    | --- | --- | --- | --- |
    | `2026-01-10T18:00:00Z` | `Asia/Kolkata` | 23:30 | `2026-01-11T02:30:00Z` |
    | `2026-01-10T18:00:00Z` | `America/New_York` | 13:00 | at once |
    | `2026-01-11T01:00:00Z` | `Asia/Kolkata` | 06:30 | `2026-01-11T02:30:00Z` |
    | `2026-03-28T22:30:00Z` | `Europe/Berlin` | 23:30 | `2026-03-29T06:00:00Z` |
    | `2026-10-24T21:30:00Z` | `Europe/Berlin` | 23:30 | `2026-10-25T07:00:00Z` |
    
    The last two are the nights the clocks change in Berlin. A fixed offset gets
    both wrong by an hour.
    
    The quiet period can cross midnight, as here, or not. A phone with a time zone
    the database does not know is treated as UTC.
    
    ## What the app must do
    
    1. Ask for permission to notify at a moment that makes sense to the person, not
       on first launch.
    2. Send the token to `POST /api/devices` on every launch and whenever the system
       gives a new one.
    3. Tell the server on sign-out, before the session is dropped.
    4. When a notification is tapped, open the address in its `data.link`.
    5. When the person reads notifications, call the server so badges on their other
       phones are set.
    
    ## Configuration
    
    | Secret | Purpose |
    | --- | --- |
    | `DATABASE_URL` | Connection string for the chosen database. |
    | `APNS_KEY`, `APNS_KEY_ID`, `APNS_TEAM_ID`, `APNS_BUNDLE_ID` | Apple's push key and what goes with it. Not needed without iOS. |
    | `FCM_SERVICE_ACCOUNT` | The Firebase service account, as JSON. Not needed without Android. |
    
    ## Named here
    
    - A payload's size is the size of the JSON sent to the push service, without the
      device token.
    - Quiet hours that start and end at the same time mean no quiet hours.
    
    ## 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 in design.md, a clock that tests can set, the adapter interface and a stand-in service. If there is no server yet, build the smallest one: users who can sign in from a phone. Check: migrations run from empty.
    2. Phones (R1). Check: the R1 acceptance tests pass.
    3. Send (R2). The list of types, push, and the cut that keeps a payload under its size. Check: the R2 acceptance tests pass.
    4. Quiet hours (R6). Only if quiet_hours is on. A pure function from a time, a time zone, quiet_start and quiet_end to when to send. Check: a test covers every row of the table of cases in design.md.
    5. The worker, retries and dead tokens (R4, R5). Against the stand-in. Check: the R4 and R5 acceptance tests pass.
    6. The real adapters (R3). For the targets input. Check: each row of the table of answers in design.md has a test, and the sign-in is reused.
    7. Preferences (R7) and badges (R8). R8 only if badge_counts is on. Check: the R7 and R8 acceptance tests pass.
    8. A record (R9). Check: the R9 acceptance tests pass.
    9. 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 in `design.md`, a clock that tests can set, the
       adapter interface and a stand-in service. If there is no server yet, build
       the smallest one: users who can sign in from a phone.
       Check: migrations run from empty.
    
    2. **Phones (R1).**
       Check: the R1 acceptance tests pass.
    
    3. **Send (R2).** The list of types, `push`, and the cut that keeps a payload
       under its size.
       Check: the R2 acceptance tests pass.
    
    4. **Quiet hours (R6).** Only if `quiet_hours` is on. A pure function from a
       time, a time zone, `quiet_start` and `quiet_end` to when to send.
       Check: a test covers every row of the table of cases in `design.md`.
    
    5. **The worker, retries and dead tokens (R4, R5).** Against the stand-in.
       Check: the R4 and R5 acceptance tests pass.
    
    6. **The real adapters (R3).** For the `targets` input.
       Check: each row of the table of answers in `design.md` has a test, and the
       sign-in is reused.
    
    7. **Preferences (R7) and badges (R8).** R8 only if `badge_counts` is on.
       Check: the R7 and R8 acceptance tests pass.
    
    8. **A record (R9).**
       Check: the R9 acceptance tests pass.
    
    9. **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
mobile, backend

What does it need?

Accounts
An Apple Developer account with a push key, for iOS, A Firebase project, for Android
Agent permissions
shell, network
Secrets it reads
DATABASE_URL APNS_KEY APNS_KEY_ID APNS_TEAM_ID APNS_BUNDLE_ID FCM_SERVICE_ACCOUNT

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/push-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.