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