Waiting Lists

Waiting Lists is a self-hosted, email-only waiting-list service with double opt-in, a private dashboard, an agent-ready API and CLI, CSV exports, and privacy-minded retention controls.

Current release: 1.0 (1.0.0 in package metadata). See CHANGELOG.md for release notes.

This download package was created from commit 71bc1c9e86ba04f5fe73d372d8f2f23bc56ed79d dated 2026-07-31. Live credentials, account identifiers, analytics, deployment history, dependencies, and build output are intentionally excluded.

What is included

• Complete Astro and TypeScript source in code/
• Cloudflare Worker, D1 migrations, Queue consumer, Cron cleanup, rate limits, Turnstile, and Email Service integration
• Admin authentication, waiting-list management, delivery status, and CSV exports
• Public HTML/JSON subscription endpoint with per-list origin controls
• Private JSON API and complete command-line client for terminal use, AI agents, and automation
• Dedicated CLI.md guide with setup, command reference, common workflows, and credential handling
• Automated tests for authentication, API keys, consent tokens, CSV, email events, country data, Turnstile, and validation
• Human setup instructions here and dedicated instructions for AI coding agents in AGENTS.md

Human quick start

1. Prerequisites

Install Node.js 22 or newer. Create a Cloudflare account if you want to use the included deployment path.

2. Install and verify

cd code
npm ci
npm run check
npm test

3. Create local settings

cp .dev.vars.example .dev.vars

Replace every placeholder in .dev.vars. Generate separate random values for SESSION_SECRET and SUBSCRIBER_TOKEN_SECRET. Generate ADMIN_PASSWORD_HASH from a strong password:

printf %s 'your-high-entropy-password' | openssl dgst -sha256

4. Prepare the local database

npm run db:migrate:local
npm run dev

Open the local URL shown by Astro, then visit /login and sign in with the administrator credentials from .dev.vars.

5. Create and connect a list

Create a waiting list in the dashboard. Add the exact browser origins that may submit to it. The list page generates ready-to-copy HTML, JavaScript, and an AI-agent integration brief.

6. Use the included CLI

Create an API key at /admin/agent, then follow CLI.md to configure the command-line client without putting the key in shell history.

npm run waitinglists -- help
npm run waitinglists -- init --name "My product" --origin "https://example.com"

The CLI can create, list, inspect, update, integrate, and export waiting lists. It runs from code/cli/waitinglists.mjs and uses the private API included in this package.

Before deploying, continue with CONFIGURATION.md, SECURITY.md, and DEPLOYMENT.md.

Project map

• code/src/pages/ — public, admin, and API routes
• code/src/lib/ — auth, database, consent, email, API keys, validation, and exports
• code/src/worker.ts — Worker entry, Queue consumer, and scheduled cleanup
• code/migrations/ — D1 schema history
• code/cli/ — complete command-line client for people, coding agents, and automation
• code/wrangler.jsonc — portable Cloudflare configuration with placeholders

Change the stack

The included Astro and Cloudflare implementation is a working reference, not a lock-in contract. The behavior, data model, edge cases, and tests are the blueprint. You can ask an AI coding agent to move the UI, database, email provider, framework, or deployment platform while preserving the product contract described in these documents.

Read AGENTS.md first when handing the package to an AI coding agent.

The download includes a working Waiting Lists CLI in code/cli/waitinglists.mjs. It uses the included private JSON API, so you can manage waiting lists from a terminal or let a coding agent do it through a small, predictable command set.

The CLI runs directly from this repository. It is not a separately published npm package and does not require a global install.

Before you start

1. Install the project and run the database migrations as described in README.md.
2. Start the app locally or deploy it to infrastructure you control.
3. Sign in to the private dashboard and open /admin/agent.
4. Create an API key. Copy it when shown because the app stores only its hash.

Configure the CLI

From code/, pass the key through standard input so it does not appear in shell history:

read -s WAITINGLISTS_API_KEY
printf %s "$WAITINGLISTS_API_KEY" | npm run waitinglists -- configure \
  --key-stdin \
  --api-url https://waiting-lists.example/api/v1
unset WAITINGLISTS_API_KEY

For local development, omit --api-url. The CLI defaults to http://localhost:4321/api/v1.

The CLI saves credentials to ~/.config/waitinglists/credentials.json with owner-only permissions. You can instead provide WAITINGLISTS_API_KEY and WAITINGLISTS_API_URL as environment variables.

Create and link a list

Run this from the website project that will use the waiting list:

node /path/to/waiting-lists/code/cli/waitinglists.mjs init \
  --name "My product" \
  --origin "https://example.com"

init creates the list and writes .waitinglists.json in the current directory. This file contains the non-secret list ID, slug, and public collection endpoint. It is safe to commit if your project benefits from sharing that link.

If you run the command from inside the downloaded code/ directory, use the shorter form:

npm run waitinglists -- init --name "My product" --origin "https://example.com"

Commands

waitinglists configure --key-stdin [--api-url URL]
waitinglists init --name NAME --origin URL [--slug SLUG] [--json]
waitinglists create --name NAME --origin URL [--slug SLUG] [--json]
waitinglists lists [--json]
waitinglists show [LIST_ID] [--json]
waitinglists update [LIST_ID] [--name NAME] [--slug SLUG] [--origin URL] [--json]
waitinglists integration [LIST_ID] [--json]
waitinglists export [LIST_ID] [--format archive|universal|sendy|kit|mailchimp] --output FILE

Use npm run waitinglists -- help to print the same reference in the terminal.

Most commands accept a list ID. After init, commands run in the linked project can read the ID from .waitinglists.json instead.

Common workflows

List every waiting list:

npm run waitinglists -- lists

Print the linked list and its subscriber summary as JSON:

npm run waitinglists -- show --json

Get the public endpoint and generated form markup:

npm run waitinglists -- integration

Change the allowed browser origin:

npm run waitinglists -- update --origin "https://www.example.com"

Export confirmed subscribers without printing personal data to the terminal:

npm run waitinglists -- export \
  --format universal \
  --output confirmed-subscribers.csv

The export command refuses to overwrite an existing file and creates the new file with owner-only permissions.

Coding-agent use

Give your coding agent this package and ask it to read AGENTS.md and CLI.md. The agent can then use --json for structured output, create or inspect a list, fetch its integration markup, and connect the public form.

Do not put an API key in AGENTS.md, .waitinglists.json, prompts, source files, or Git. Configure it once through standard input or expose it to a trusted process through WAITINGLISTS_API_KEY.

Troubleshooting

• No API key configured means the credentials file and WAITINGLISTS_API_KEY are both missing.
• 401 Unauthorized means the key is invalid or has been revoked in /admin/agent.
• No list ID supplied means the current directory has no .waitinglists.json; pass a list ID or run init.
• Origin errors mean the collecting site's exact browser origin is missing from the list configuration.

Overview

Waiting Lists is an Astro server-rendered application deployed through a Cloudflare Worker. D1 stores lists, subscribers, consent evidence, admin sessions, API keys, settings, and email delivery events. Cloudflare Email Service sends confirmation messages, a Queue reports delivery outcomes, and a Cron Trigger removes expired or over-retained records.

Request flow

1. An administrator creates a list and configures allowed browser origins.
2. A public form posts exactly email and consent to /api/subscribe/[slug].
3. Validation, origin rules, and rate limits run before D1 changes.
4. A pending subscriber and hashed one-time confirmation token are stored.
5. Email Service sends a confirmation link and a separate removal link.
6. The person reviews and confirms; the token is consumed and the subscriber becomes confirmed.
7. The dashboard and exports expose confirmed subscribers to the authenticated administrator.
8. Queue events update delivery status. Scheduled cleanup removes expired pending requests and old confirmed records.

Main boundaries

• src/pages/api/subscribe/[slug].ts — public collection boundary
• src/pages/admin/ — private human interface
• src/pages/api/v1/ — private agent/API boundary
• cli/waitinglists.mjs — included command-line client for people, coding agents, and automation
• src/lib/auth.ts — password, session, cookie, and CSRF rules
• src/lib/subscriber-tokens.ts — confirmation and removal token rules
• src/lib/db.ts — database queries and lifecycle operations
• src/lib/email.ts and email-events.ts — outbound mail and delivery events
• src/lib/integration.ts — machine-readable integration contract
• src/worker.ts — HTTP entry, scheduled cleanup, and Queue consumer
• migrations/ — source of truth for the D1 schema

Replaceable infrastructure

Cloudflare is the reference implementation. A port can replace D1 with PostgreSQL, Email Service with another transactional provider, Queues with a job runner, Turnstile with another abuse-control layer, and Workers with any server runtime. Preserve the boundaries and acceptance behavior above rather than translating files line by line.