# Waitlist with referrals ## What this builds A waiting list for an app that is not open to everyone yet. A person leaves their email address and confirms it. They can move up the line by sending others, and the team lets people in a batch at a time. The rules for counting are exact, and written so the cheap ways of jumping the line do not work. Read `spekkr.inputs.json` first. `referrals` decides whether R3 exists, and each referral is worth `referral_boost` places. `show_position` changes R5. Use `app_name` on the pages and in every email. ## Out of scope - The app's own sign-up. R7 is the one function it calls. - Paying to move up. - Prizes and leaderboards. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Join - A person gives an email address. It is trimmed and lowercased. - For telling whether someone already joined, a tag after a plus sign is ignored, and for Gmail addresses so are full stops: `sam+a@example.com` is `sam@example.com`, and `s.a.m@gmail.com` is `sam@gmail.com`. Email is still sent to the address they gave, trimmed and in lowercase, not to the key. - The answer is the same whether the address is new or already on the list. A person already on it is sent their status link again. - The form has a field people cannot see. A request that fills it in is answered as if it worked and nothing is stored. - One IP address can join 5 times an hour. Accept when: `Sam+x@Example.com` and `sam@example.com` are one entry, the answer to both requests is the same, and the sixth join from an address in an hour is refused. ### R2. Confirm - Joining sends a link that confirms the address. It works for 48 hours. - Only confirmed entries have a place in line, count as referrals, or can be invited. - The link shows a page with one button, and the button confirms. A mail scanner that opens the link confirms nothing. Accept when: fetching the link with `GET` alone confirms nothing, pressing the button does, and an entry not confirmed in 48 hours is deleted. ### R3. Referrals Only if `referrals` is on. - Each confirmed entry has a link to share, with a code of 8 letters and digits. - A person who joins through the link and then confirms counts as one referral for its owner. - These do not count: a person referring an address that is the same as theirs by the rule in R1; a referred entry that joined from the same IP address as its referrer; and more than 5 referred entries from one IP address in a day, whoever referred them. - A referral that does not count is still a normal entry. Nobody is told which referrals counted. Accept when: each of the three rules has a test, and a referral counts only after the referred person confirms. ### R4. The line - A person's score is their place by time of confirming, minus `referral_boost` for each referral that counts. - The line is ordered by score, lowest first. Equal scores go by who confirmed first. - A person's place is their position in that order, starting at 1. Accept when: the table in `design.md` is reproduced exactly. ### R5. Status page - Every email holds a link to the person's own status page. The link carries a signed token, so nobody can read another person's page by guessing. - The page shows, if `show_position` is on, the person's place and how many are ahead; and if `referrals` is on, their link to share and how many referrals have counted. - "Take me off the list" deletes the entry after one confirmation. Accept when: a changed token is refused, and after "Take me off the list" the address is in no table. ### R6. Invite - An administrator invites the first N people in line, or picks people by hand. - Each invited person gets an email with a code that works once, for 7 days, and leaves the line. - An invitation that runs out puts the person back at the place their score gives them. They are told, once. Accept when: inviting 3 invites the first three by R4, and an invitation unused after 7 days puts its person back in line. ### R7. Let them in - The app's sign-up calls `redeem(code, email)`. It answers yes once, for the address the code was sent to, compared by the rule in R1. - Redeeming marks the entry as joined, and it is kept as a record that the person came from the list. Accept when: a code works once, fails for another address, and fails after 7 days. ### R8. For the team - A page with the counts: joined, confirmed, invited, redeemed. The line, with each person's score and referrals. A download of the list as CSV. - Only administrators reach it. Accept when: the counts match the table after each step of a test that joins, confirms, invites and redeems. ### R9. Pages - The form, "check your email", the confirm page, the status page, and the team's page. 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 put the form on a page, how to call `redeem` from sign-up, and how to run the tests.