mirror of https://github.com/hanzo-apps/waitlist.git synced 2026-10-30 14:48:32 +00:00

Files

T

zeekay aeb4e51516 feat(apps/mock-api): reference impl of /v1/waitlist/* contract

Adds apps/mock-api/ — a ~200-line Node http server that implements the
exact wire format of plugins/waitlist (Base Go plugin). Used by the
demo so the full Join → Success-with-rank-and-share flow works
standalone with no Base instance. Doubles as an executable spec for
anyone reimplementing the contract in another language.

Storage is in-memory; restart drops state. Implements:
- POST /v1/waitlist/join     idempotent on (waitlist, email), atomic
                             referral credit, collision-safe refCode
- GET  /v1/waitlist/status   rank + share URL
- GET  /v1/waitlist/export   CSV, Bearer-auth via WAITLIST_ADMIN_SECRET

Same anti-abuse defenses as the Go plugin: crypto/rand refCodes from a
36-char alphabet that excludes confusing glyphs, disposable email
blocklist, per-IP sliding-window rate limit (5/IP/hour default), email
normalization. Turnstile is a host-side concern in the mock.

Wired into the demo via NEXT_PUBLIC_BASE_URL=http://localhost:8090.
README updated to document the two-terminal dev flow.

2026-06-10 08:08:12 -07:00

2.6 KiB

Raw Permalink Blame History

Hanzo Waitlist

中文

Monochromatic, brand-neutral viral waitlist. No logos, no brand colors, no embedded identity — each consumer brings its own. Backed by Hanzo Base; no Redis, no third-party SaaS.

import { Waitlist } from '@hanzo/waitlist'
import '@hanzo/waitlist/styles.css'

<Waitlist waitlist="my-product" baseUrl="https://api.example.com" />

What's in this repo

Path	What
`packages/widget/`	`@hanzo/waitlist` — React + framework-free client + custom element
`apps/web/`	Demo site (Next.js) — brand-swappable preview
`docs/`	architecture, api, widget

The server lives in a different repo: ~/work/hanzo/base under plugins/waitlist/. Register it on any Base process:

import "github.com/hanzoai/base/plugins/waitlist"

waitlist.MustRegister(app, waitlist.Config{
    Enabled:         true,
    TurnstileSecret: os.Getenv("TURNSTILE_SECRET_KEY"),
    AdminSecret:     os.Getenv("WAITLIST_ADMIN_SECRET"),
})

Two collections (waitlists, waitlist_entries) are created on first boot. Three endpoints are mounted under /v1/waitlist.

Quick start (dev)

pnpm install
pnpm --filter @hanzo/waitlist build

# Terminal 1: backend (mock reference impl, in-memory)
pnpm --filter @hanzo/waitlist-mock-api dev   # listens on :8090

# Terminal 2: demo
NEXT_PUBLIC_BASE_URL=http://localhost:8090 \
  pnpm --filter @hanzo/waitlist-demo dev     # http://localhost:3000

For production you swap mock-api for a real Hanzo Base instance with plugins/waitlist registered. The mock implements the exact same /v1/waitlist/{join,status,export} contract — it's both the demo backend and the executable spec.

Theming

Zero brand colors in the widget. Bring your own selector + variables:

.your-brand {
  --hw-accent: <your accent color>;
  --hw-accent-fg: <text on accent>;
  --hw-radius: <corner radius>;
}

Logos, headlines, and any embedded identity are the host's responsibility. The widget itself ships fully neutral.

Full variable list: docs/widget.md.

API

Endpoint	Purpose
`POST /v1/waitlist/join`	Register an entry, credit referrer atomically
`GET /v1/waitlist/status`	Look up rank + share URL
`GET /v1/waitlist/export`	Admin CSV (superuser or shared-secret gated)

Wire format: docs/api.md.

License

MIT.

2.6 KiB Raw Permalink Blame History