Kicksmash

Kicksmash — padel match-up in one link

Mobile-first web app for organizing padel matches with zero app installs, zero accounts, zero passwords. Create a match, share kicksma.sh/{code} on WhatsApp or Telegram, friends tap → enter a name once → they're in.

• Stack: Next.js 15 (App Router, TypeScript) · Supabase Postgres + Drizzle · Resend · next-intl (EN/RU/ES) · Tailwind v4 · Vercel (Cron + OG images).
• Open source under the Apache License 2.0. Run your own copy, build on it, send a PR: see CONTRIBUTING.md and SECURITY.md.
• Identity: one-time name entry → player UUID in a signed httpOnly cookie (1 year) + a restore seal in localStorage (the server signs it for that player and that purpose; a lost cookie comes back from the seal, never from a bare player id). Cross-device: every player has a private personal link (/p/{token}, shown on My matches, in every email and in the calendar invite) that signs any device in; an email that was used before can restore history with a 6-digit code, merging all identities that share it. The home-screen shortcut opens the personal link, and calendar entries and emails carry the private event link (/p/{token}/{code}: signs the device in, opens the match). A newly added email receives the personal link (inside the calendar invite when in a match, otherwise on its own). Tokens are 12 characters; older 32-char tokens keep working as previous_token after the lazy shortening. An email can be changed but never blanked once set; the previous address is kept as recovery_email, so a restore code sent to either address gets the player back in. "Email me this link" on My matches mails the personal link (native share, copy and QR are the other options). Passkeys (DECIDING rule 39): after a join, "Remember me on this phone" saves a passkey in the phone's password manager, and from then on "Sign in with Face ID or fingerprint" signs any browser on that phone in, first in "Played before?", which stands open under the name field of the match page's join form. A session by name never saves one; a sign-in folds only the bare new record of the same name that this browser made. Kicksmash keeps the public key, a label and two dates (passkeys), and My matches lists "Phones that remember you" with Remove.
• Notices, quiet hours and an inbox: every notice to a player passes one gate (src/lib/domain/notices.ts): it lands in their inbox on My matches first (ninety days, newest first, in the reader's language), and goes out on their channel only when that kind is on (seven kinds, all on but the club's new matches) and it is not their quiet hours, unless the match starts within three hours. What quiet hours held goes as one short message per channel when they end, from the hourly cron.
• Push reminders: Web Push (VAPID) one hour before each match, for every device the player enabled it on (iPhone: from the home-screen app). /api/cron/push is called every 5 minutes by Supabase pg_cron + pg_net (Vercel Hobby cron is daily). Set VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT.
• Links: /{code} (4 chars, public) · /{code}/i/{6} (personal invite) · /{code}/manage/{10} (organizer secret).
• Agent-native and open. A public REST API (OpenAPI 3.1 at /api/openapi.json), an MCP server at /mcp that any assistant adds by URL, instant self-serve keys, signed webhooks, llms.txt, /.well-known/mcp.json, a robots.txt that welcomes AI crawlers, AGENTS.md, an installable skill (npx skills add evhg/padel-matchup), calendar feeds per group and venue. Public data is CC BY 4.0. See /developers and /agents.
• Email is optional everywhere. Without RESEND_API_KEY the app runs fully with email features hidden.
• Privacy, short and in full: /about says what is stored, what is never done, and how to leave, in a few lines; /privacy (the one faint footer link) and /terms say it in full, with the cookies, the processors and the figures the code enforces (src/lib/legal.ts). Every organizer-initiated email (invites, invite reminders) carries a signed one-tap /unsubscribe link; a player adding their own address again lifts the opt-out. "Delete my account" at the bottom of My matches wipes personal data (name, email, phone, personal link, the linked Telegram, Discord and LINE accounts, the public page, the passkeys), releases upcoming spots, cancels the player's own upcoming matches, and — if they coach — cancels their upcoming lessons (each student told, with the coach's real name) and takes their coach page down with everything on it; old scores stay as "Deleted player". A coach who wants only the page gone, keeping the account, has "Delete my coach page" at the bottom of their settings, which refuses while a lesson is still to come.
• Levels: every player can declare a padel level (0–7 in quarter steps, the scale the padel apps use) once, from My matches or the first time a ranged match asks for it. It shows as a small chip next to the name everywhere (roster, standings, team picker). Results nudge it: when the organizer confirms a 2v2 score or finalizes a tournament, a small Elo-style delta (at most ±0.10 per match, ±0.12 per tournament) is applied once per event and logged ("3.25 → 3.30 after a match"). Players without a level neither move nor count. Organizers can set a level range per match or tournament: presets Bronze 1.0–2.5, Silver 2.5–3.5, Gold 3.0–4.5, Platinum 4.5+, or a custom min–max. Players inside join as usual; players outside ask to join and the organizer approves (seats them, or waitlists them when full) or declines, with the answer shown in the join bar and the activity feed. Reserved/invited players and the organizer bypass the range. The score panel suggests balanced teams (smallest level gap) when all four have levels. My matches gets a stats strip: played, won, win rate, podiums.
• Abuse limits (per UTC day unless noted, generous for humans, tight for scripts): 40 new identities per IP, 20 matches per player, 40 invitations per organizer, 30 joins per player per hour, 10 email changes, 5 personal-link mails, 20 restore codes per IP, 60 browser crash reports per IP. Counters live in metrics_daily, no extra infrastructure. Hitting one returns "too many" and nothing else happens.

---

Quick start (zero config, ~2 min)

pnpm install

pnpm dev

That's it. With no DATABASE_URL the app boots an embedded PGlite database in ./.pglite, applies migrations and seeds two example events:

Copy .env.example to .env to change anything. All flows (join, waitlist, invites, scores, "My matches", OG previews) work end-to-end without any keys.

pnpm test        # vitest: slot-claim concurrency, invite transitions, score-lock rules, reminders, identity, americano rotation, rate limits, opt-outs, account deletion

pnpm typecheck pnpm lint pnpm build pnpm e2e # the sixteen Playwright journeys against a fresh production build (node scripts/suites.mjs --why says which a change can break); first time: pnpm exec playwright install chromium

pnpm e2e boots next start on port 3001 with a throwaway PGlite database, a dummy Resend key (email UIs on, sends fail harmlessly) and generated VAPID keys, then runs every e2e/*.mjs suite. SHOTS=./shots keeps full-page screenshots; PW_CHROMIUM=/path/to/chromium uses a preinstalled browser. GitHub Actions runs typecheck, lint, vitest on PGlite and on a real Postgres service, the build, and the e2e suites on every push and pull request (.github/workflows/ci.yml).

Tests run on in-memory PGlite by default. To run them against a real Postgres (true concurrency), point TEST_DATABASE_URL at a disposable database — its public schema is dropped before each test file:

TEST_DATABASE_URL=postgres://postgres:postgres@localhost:5432/padel_test pnpm test

---

Environment variables

Only one variable is required in production: the database URL. Everything else has a safe default.

| WHATSAPP_TOKEN / WHATSAPP_PHONE_ID / WHATSAPP_NUMBER / WHATSAPP_VERIFY_TOKEN / WHATSAPP_APP_SECRET | no | Enables the WhatsApp thread: one person at a time, not a card channel. Meta's Groups API makes only the business's own groups, joined by an invite link. A group holds eight people at most, needs an Official Business Account, and allows no edit of a message. So the bot can never sit in a chat the crew already has. A group that the bot makes waits for the owner's Meta steps (ROADMAP.md). Point Meta