Waitlist with referrals

A waitlist where people confirm their email, move up by referring others and are invited in batches, with rules that resist gaming.

This is an app part spec on Spekkr, published by juno. 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
juno/waitlist
Version
0.1.2
Published by
juno
Updated
15 Nov 2026

Build this spec

Build the spec at https://spekkr.com/juno/waitlist/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 juno.

What does the result look like?

Waitlist with referrals: join formWaitlist with referrals: status placeWaitlist with referrals: team lineWaitlist with referrals: join form mobile

What can I customize?

Database

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.

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

    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
    waitlist_entriesid, email (trimmed, lowercase), email_key (unique; by the rule in R1), code (unique), referred_by, referral_counts, ip, state, joined_at, confirmed_at, confirm_order
    waitlist_invitesid, entry_id, code_hash (unique), sent_at, expires_at, redeemed_at

    state is one of pending, confirmed, invited and joined. confirm_order is 1 for the first entry to confirm, 2 for the second, and so on, given in the transaction that confirms. referral_counts says whether this entry counts as a referral for the entry in referred_by.

    The line

    score = confirm_order - boost * (number of entries that count as its referrals)

    boost is the referral_boost input. Order by score, then by confirm_order. Only entries in state confirmed are in the line; an invited person's place closes up behind them.

    Seven people, with a boost of 3:

    PlacePersonConfirmed as numberReferrals that countScore
    1gus74-5
    2dev42-2
    3ana101
    4ben202
    5cho303
    6fay613
    7eli505

    cho and fay both score 3. cho confirmed first, so cho is ahead.

    Work the line out with one query that sorts. Do not store places: every referral would change many rows.

    Rules

    • Decide whether a referral counts once, when the referred entry confirms, and store the answer. Later changes to the rules do not rewrite the past.
    • The three rules of R3 need the IP address of each join. Delete it 30 days after the entry confirms.
    • The status token is the entry's id, a full stop, and an HMAC-SHA-256 of the id keyed with WAITLIST_SECRET, both in base64url. Compare in constant time.
    • Invitation codes are 10 random letters and digits, stored as SHA-256 hashes.
    • Put sending behind one small interface so tests capture messages without a network. Four messages: confirm, you are on the list, you are invited, your invitation ran out. Use the app_name input in each.
    • In CSV, put a single quote in front of any cell that starts with =, +, - or @.

    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.
    WAITLIST_SECRETSigns status 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

    • "In a day" is the last 24 hours. googlemail.com counts as Gmail.

    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 |
    | --- | --- |
    | `waitlist_entries` | `id`, `email` (trimmed, lowercase), `email_key` (unique; by the rule in R1), `code` (unique), `referred_by`, `referral_counts`, `ip`, `state`, `joined_at`, `confirmed_at`, `confirm_order` |
    | `waitlist_invites` | `id`, `entry_id`, `code_hash` (unique), `sent_at`, `expires_at`, `redeemed_at` |
    
    `state` is one of `pending`, `confirmed`, `invited` and `joined`. `confirm_order`
    is 1 for the first entry to confirm, 2 for the second, and so on, given in the
    transaction that confirms. `referral_counts` says whether this entry counts as a
    referral for the entry in `referred_by`.
    
    ## The line
    
    ```
    score = confirm_order - boost * (number of entries that count as its referrals)
    ```
    
    `boost` is the `referral_boost` input. Order by `score`, then by `confirm_order`.
    Only entries in state `confirmed` are in the line; an invited person's place
    closes up behind them.
    
    Seven people, with a boost of 3:
    
    | Place | Person | Confirmed as number | Referrals that count | Score |
    | --- | --- | --- | --- | --- |
    | 1 | `gus` | 7 | 4 | -5 |
    | 2 | `dev` | 4 | 2 | -2 |
    | 3 | `ana` | 1 | 0 | 1 |
    | 4 | `ben` | 2 | 0 | 2 |
    | 5 | `cho` | 3 | 0 | 3 |
    | 6 | `fay` | 6 | 1 | 3 |
    | 7 | `eli` | 5 | 0 | 5 |
    
    `cho` and `fay` both score 3. `cho` confirmed first, so `cho` is ahead.
    
    Work the line out with one query that sorts. Do not store places: every referral
    would change many rows.
    
    ## Rules
    
    - Decide whether a referral counts once, when the referred entry confirms, and
      store the answer. Later changes to the rules do not rewrite the past.
    - The three rules of R3 need the IP address of each join. Delete it 30 days after
      the entry confirms.
    - The status token is the entry's id, a full stop, and an HMAC-SHA-256 of the id
      keyed with `WAITLIST_SECRET`, both in base64url. Compare in constant time.
    - Invitation codes are 10 random letters and digits, stored as SHA-256 hashes.
    - Put sending behind one small interface so tests capture messages without a
      network. Four messages: confirm, you are on the list, you are invited, your
      invitation ran out. Use the `app_name` input in each.
    - In CSV, put a single quote in front of any cell that starts with `=`, `+`, `-`
      or `@`.
    
    ## 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. |
    | `WAITLIST_SECRET` | Signs status 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
    
    - "In a day" is the last 24 hours. `googlemail.com` counts as Gmail.
    
    ## 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, and a way to capture email in tests. Check: migrations run from empty.
    2. The same address (R1). A pure function from an address to its key. Check: tests cover a plus tag, Gmail full stops, case, and an address that must stay as it is.
    3. Join and confirm (R1, R2). Use the app_name input in the emails. Check: the R1 and R2 acceptance tests pass.
    4. Referrals (R3). Only if referrals is on. Check: the R3 acceptance tests pass.
    5. The line (R4). One query, using the referral_boost input. Check: a test builds the seven people in design.md and gets the table.
    6. Status page (R5). Honour show_position. Check: the R5 acceptance tests pass.
    7. Invite and let in (R6, R7). Check: the R6 and R7 acceptance tests pass.
    8. For the team (R8) and pages (R9). Check: the R8 test passes, and every page can be used with a keyboard alone and at 360 pixels wide.
    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, and a
       way to capture email in tests.
       Check: migrations run from empty.
    
    2. **The same address (R1).** A pure function from an address to its key.
       Check: tests cover a plus tag, Gmail full stops, case, and an address that
       must stay as it is.
    
    3. **Join and confirm (R1, R2).** Use the `app_name` input in the emails.
       Check: the R1 and R2 acceptance tests pass.
    
    4. **Referrals (R3).** Only if `referrals` is on.
       Check: the R3 acceptance tests pass.
    
    5. **The line (R4).** One query, using the `referral_boost` input.
       Check: a test builds the seven people in `design.md` and gets the table.
    
    6. **Status page (R5).** Honour `show_position`.
       Check: the R5 acceptance tests pass.
    
    7. **Invite and let in (R6, R7).**
       Check: the R6 and R7 acceptance tests pass.
    
    8. **For the team (R8) and pages (R9).**
       Check: the R8 test passes, and every page can be used with a keyboard alone
       and at 360 pixels wide.
    
    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
web, backend

What does it need?

Accounts
An email-sending service
Agent permissions
shell, network
Secrets it reads
DATABASE_URL EMAIL_API_KEY WAITLIST_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/waitlist.

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