Add pricing-page waitlist (name + email signup)

Replaces the disabled "Coming soon" buttons on the pricing page with a
waitlist band so visitors can be notified when alerts launch — separate
from registered users.

- waitlist_subscribers table (name, email unique, source, referrer)
- WaitlistService::subscribe — normalises email, idempotent
- Public POST /api/waitlist (throttle:10,1), thin controller + form request
- Read-only Filament resource with streamed CSV export
- Vue: useWaitlist composable + WaitlistForm, rendered below the grid
  while any tier is still "coming soon"; sends source + document.referrer

Announcement send mechanism deferred to a later task.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/Filament/Resources/WaitlistSubscriberResource.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace App\Filament\Resources;
+
+use App\Filament\NavigationGroup;
+use App\Filament\Resources\WaitlistSubscriberResource\Pages\ListWaitlistSubscribers;
+use App\Models\WaitlistSubscriber;
+use Filament\Resources\Resource;
+use Filament\Tables\Columns\TextColumn;
+use Filament\Tables\Table;
+
+class WaitlistSubscriberResource extends Resource
+{
+    protected static ?string $model = WaitlistSubscriber::class;
+
+    protected static string|\UnitEnum|null $navigationGroup = NavigationGroup::Users;
+
+    protected static ?string $navigationLabel = 'Waitlist';
+
+    protected static ?int $navigationSort = 3;
+
+    public static function canCreate(): bool
+    {
+        return false;
+    }
+
+    public static function table(Table $table): Table
+    {
+        return $table
+            ->columns([
+                TextColumn::make('name')
+                    ->searchable(),
+                TextColumn::make('email')
+                    ->searchable()
+                    ->copyable(),
+                TextColumn::make('source')
+                    ->badge()
+                    ->placeholder('—')
+                    ->toggleable(),
+                TextColumn::make('referrer')
+                    ->limit(40)
+                    ->placeholder('—')
+                    ->toggleable(isToggledHiddenByDefault: true),
+                TextColumn::make('created_at')
+                    ->label('Joined')
+                    ->dateTime('d M Y H:i')
+                    ->sortable(),
+            ])
+            ->defaultSort('created_at', 'desc')
+            ->recordActions([])
+            ->filters([]);
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index' => ListWaitlistSubscribers::route('/'),
+        ];
+    }
+}

app/Filament/Resources/WaitlistSubscriberResource/Pages/ListWaitlistSubscribers.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\Filament\Resources\WaitlistSubscriberResource\Pages;
+
+use App\Filament\Resources\WaitlistSubscriberResource;
+use App\Models\WaitlistSubscriber;
+use Filament\Actions\Action;
+use Filament\Resources\Pages\ListRecords;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+class ListWaitlistSubscribers extends ListRecords
+{
+    protected static string $resource = WaitlistSubscriberResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            Action::make('export')
+                ->label('Export CSV')
+                ->icon('heroicon-o-arrow-down-tray')
+                ->action(fn (): StreamedResponse => response()->streamDownload(function (): void {
+                    $handle = fopen('php://output', 'wb');
+
+                    fputcsv($handle, ['name', 'email', 'source', 'referrer', 'joined_at']);
+
+                    WaitlistSubscriber::query()
+                        ->orderBy('created_at')
+                        ->each(function (WaitlistSubscriber $subscriber) use ($handle): void {
+                            fputcsv($handle, [
+                                $subscriber->name,
+                                $subscriber->email,
+                                $subscriber->source,
+                                $subscriber->referrer,
+                                $subscriber->created_at?->toDateTimeString(),
+                            ]);
+                        });
+
+                    fclose($handle);
+                }, 'waitlist.csv', ['Content-Type' => 'text/csv'])),
+        ];
+    }
+}

app/Http/Controllers/Api/WaitlistController.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\StoreWaitlistRequest;
+use App\Services\WaitlistService;
+use Illuminate\Http\JsonResponse;
+
+class WaitlistController extends Controller
+{
+    public function __construct(private readonly WaitlistService $waitlist) {}
+
+    public function store(StoreWaitlistRequest $request): JsonResponse
+    {
+        $this->waitlist->subscribe(
+            name: $request->string('name')->toString(),
+            email: $request->string('email')->toString(),
+            source: $request->filled('source') ? $request->string('source')->toString() : null,
+            referrer: $request->filled('referrer') ? $request->string('referrer')->toString() : null,
+        );
+
+        return response()->json([
+            'message' => "You're on the list — we'll email you when alerts go live.",
+        ], 201);
+    }
+}

app/Http/Requests/Api/StoreWaitlistRequest.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Http\Requests\Api;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class StoreWaitlistRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, array<int, string>>
+     */
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'max:255'],
+            'email' => ['required', 'email', 'max:255'],
+            'source' => ['nullable', 'string', 'max:64'],
+            'referrer' => ['nullable', 'string', 'max:2048'],
+        ];
+    }
+}

app/Models/WaitlistSubscriber.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace App\Models;
+
+use Database\Factories\WaitlistSubscriberFactory;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+#[Fillable(['name', 'email', 'source', 'referrer'])]
+class WaitlistSubscriber extends Model
+{
+    /** @use HasFactory<WaitlistSubscriberFactory> */
+    use HasFactory;
+}

app/Services/WaitlistService.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\WaitlistSubscriber;
+
+final class WaitlistService
+{
+    /**
+     * Add someone to the feature-launch waitlist.
+     *
+     * Idempotent: re-subscribing an existing email is a no-op that returns the
+     * original subscriber unchanged — original meta (source, referrer) is kept,
+     * never a duplicate row or an error.
+     */
+    public function subscribe(
+        string $name,
+        string $email,
+        ?string $source = null,
+        ?string $referrer = null,
+    ): WaitlistSubscriber {
+        $email = strtolower(trim($email));
+
+        return WaitlistSubscriber::firstOrCreate(
+            ['email' => $email],
+            ['name' => $name, 'source' => $source, 'referrer' => $referrer],
+        );
+    }
+}

database/factories/WaitlistSubscriberFactory.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Models\WaitlistSubscriber;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends Factory<WaitlistSubscriber>
+ */
+class WaitlistSubscriberFactory extends Factory
+{
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        return [
+            'name' => fake()->name(),
+            'email' => fake()->unique()->safeEmail(),
+        ];
+    }
+}

database/migrations/2026_06_12_085857_create_waitlist_subscribers_table.php

@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('waitlist_subscribers', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+            $table->string('email')->unique();
+            $table->string('source', 64)->nullable()->comment('Where they joined from, e.g. pricing');
+            $table->text('referrer')->nullable()->comment('document.referrer at signup');
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('waitlist_subscribers');
+    }
+};

docs/superpowers/specs/2026-06-12-pricing-waitlist-design.md

@@ -0,0 +1,197 @@
+# Pricing-page waitlist — design
+
+**Date:** 2026-06-12
+**Status:** Approved, pending implementation plan
+
+## Problem
+
+The `/pricing` page shows disabled **"Coming soon"** buttons on the Daily
+(`basic`) and Smart (`plus`) cards, because their alerting features aren't
+shipped yet (`COMING_SOON = ['basic', 'plus']` in
+`resources/js/components/PricingGrid.vue`). We want to capture interest instead
+of showing a dead button: let a visitor leave their **name + email** to be
+notified when alerts launch.
+
+This list is **separate from registered users** — it's a marketing signup log,
+not an account.
+
+## Scope
+
+**In scope (now):**
+
+- Collect name + email from the pricing page.
+- Store in a dedicated table.
+- View + CSV export in the Filament admin panel (the "announce later" hook).
+
+**Out of scope (deliberately deferred to a later task):**
+
+- The announcement email itself — Mailable, queued bulk send, unsubscribe
+  route/link. We collect now and build the send mechanism when we're actually
+  ready to email the list.
+- Tier segmentation — we do **not** record which tier (Daily vs Smart) the
+  visitor was interested in. One flat list.
+- IP / source / user-agent capture. Can be added later if abuse becomes a
+  problem; not needed for v1.
+
+## Why not the `offload-project/laravel-waitlist` package
+
+That package is built around referrals, queue positions, and invite flows —
+none of which this needs. It would add a dependency and migrations we'd work
+against. A single table + endpoint is less code and less maintenance for
+"collect name + email, announce later."
+
+## Architecture
+
+Follows the existing shape: **Vue SPA → public REST API → thin controller →
+fat service → model** (`.claude/rules/architecture.md`,
+`.claude/rules/frontend.md`).
+
+```
+WaitlistForm.vue (below the pricing grid)
+  └── useWaitlist.js (composable, uses configured `api` axios instance)
+        └── POST /api/waitlist           (public, throttle:10,1)
+              └── Api\WaitlistController@store
+                    └── StoreWaitlistRequest (validation)
+                    └── WaitlistService::subscribe()
+                          └── WaitlistSubscriber (model)
+```
+
+## Backend
+
+### Migration — `create_waitlist_subscribers_table`
+
+| Column       | Type                  | Notes                         |
+|--------------|-----------------------|-------------------------------|
+| `id`         | bigIncrements         |                               |
+| `name`       | string                |                               |
+| `email`      | string, **unique**    | stored lowercased + trimmed   |
+| `created_at` / `updated_at` | timestamps |                          |
+
+No other columns, per the minimal-schema decision.
+
+### Model — `WaitlistSubscriber`
+
+- `$fillable = ['name', 'email']`.
+- A factory (`WaitlistSubscriberFactory`) for tests.
+
+### Service — `WaitlistService`
+
+```php
+public function subscribe(string $name, string $email): WaitlistSubscriber
+```
+
+- Normalises email: `trim` + `strtolower`.
+- `firstOrCreate(['email' => $email], ['name' => $name])` — **idempotent**.
+  Re-submitting an existing email is a no-op success, never an error and never
+  a duplicate row. Does not reveal whether the email was already present.
+- `final` class, constructor injection only (per `code-style.md`).
+- Returns the `WaitlistSubscriber` model (typed return, per `architecture.md`).
+
+### Form Request — `Api/StoreWaitlistRequest`
+
+```php
+'name'  => ['required', 'string', 'max:255'],
+'email' => ['required', 'email', 'max:255'],
+```
+
+`authorize()` returns `true` (public endpoint).
+
+### Controller — `Api\WaitlistController@store`
+
+- Thin: validates via `StoreWaitlistRequest`, calls `WaitlistService::subscribe()`.
+- Returns `201`:
+  ```json
+  { "message": "You're on the list — we'll email you when alerts go live." }
+  ```
+- Does **not** echo the model back (nothing sensitive to return; no API
+  Resource needed).
+
+### Route — `routes/api.php`
+
+Added to the **public** block (alongside `/auth/register`):
+
+```php
+Route::post('/waitlist', [WaitlistController::class, 'store'])
+    ->middleware('throttle:10,1');
+```
+
+Public (no API key, no Sanctum auth), but throttled to 10/min per IP. Uses the
+same Sanctum-stateful XSRF path as `/auth/register`, so the SPA posts to it with
+its existing axios credentials/XSRF config.
+
+## Frontend
+
+### Composable — `resources/js/composables/useWaitlist.js`
+
+Exposes:
+
+- `submit(name, email)` — `POST /waitlist` via the configured `api` instance
+  (`resources/js/axios.js`); never a bare axios/fetch call (per `frontend.md`).
+- `loading` (ref bool)
+- `error` (ref string|null) — surfaces validation/throttle errors
+- `success` (ref bool)
+
+### Component — `resources/js/components/WaitlistForm.vue`
+
+- A single shared "band" rendered **once below the pricing grid**.
+- Heading (e.g. "Want in when alerts launch?") + `name` input + `email` input +
+  "Notify me" button, laid out inline on the band.
+- States: idle → loading (button disabled/spinner) → success (inline
+  "You're on the list ✓", form hidden/replaced) or error (message shown,
+  inputs retained).
+- Tailwind styling consistent with the pricing cards
+  (`.claude/rules/code-style.md`, Tailwind v4).
+
+### `resources/js/components/PricingGrid.vue`
+
+- **No change** to the `COMING_SOON` logic — the Daily/Smart buttons stay as
+  disabled "Coming soon".
+- Render `<WaitlistForm />` once, below the `.grid` (still inside the section).
+
+## Admin — Filament `WaitlistSubscriberResource`
+
+In `app/Filament/Resources/` (matching siblings like `UserResource`).
+
+- **Table:** `name`, `email`, joined date (`created_at`). Searchable on name +
+  email; default sort newest first.
+- **CSV export:** Filament table export action — this is the mechanism for
+  pulling the list to announce later.
+- **Read-only:** no create / edit / delete actions. It's a signup log; rows
+  arrive only via the public endpoint.
+
+## Tests (Pest — `.claude/rules/testing.md`)
+
+**Feature** (`tests/Feature/`, `RefreshDatabase`, factory-first):
+
+- `POST /api/waitlist` with valid name + email → `201`, row exists.
+- Duplicate email → `201`, still exactly one row (idempotent, no error).
+- Missing name → `422`.
+- Invalid email → `422`.
+- (Throttle middleware present on the route.)
+
+**Unit** (`tests/Unit/Services/WaitlistServiceTest.php`):
+
+- `subscribe()` lowercases + trims the email before storing.
+- `subscribe()` called twice with the same email creates one row and returns
+  the existing subscriber.
+
+## Files touched
+
+**New:**
+
+- `database/migrations/xxxx_create_waitlist_subscribers_table.php`
+- `app/Models/WaitlistSubscriber.php`
+- `database/factories/WaitlistSubscriberFactory.php`
+- `app/Services/WaitlistService.php`
+- `app/Http/Requests/Api/StoreWaitlistRequest.php`
+- `app/Http/Controllers/Api/WaitlistController.php`
+- `app/Filament/Resources/WaitlistSubscriberResource/...` (resource + list page)
+- `resources/js/composables/useWaitlist.js`
+- `resources/js/components/WaitlistForm.vue`
+- `tests/Feature/WaitlistTest.php`
+- `tests/Unit/Services/WaitlistServiceTest.php`
+
+**Modified:**
+
+- `routes/api.php` (add public throttled route)
+- `resources/js/components/PricingGrid.vue` (render `<WaitlistForm />` below grid)

resources/js/components/PricingGrid.vue

@@ -80,13 +80,16 @@
                     <button v-else type="button" disabled class="w-full py-3 px-4 bg-zinc-100 rounded-xl text-center font-bold text-zinc-400 cursor-not-allowed">Coming soon</button>
                 </div>
             </div>
+
+            <WaitlistForm v-if="hasComingSoon" source="pricing" />
         </div>
     </section>
 </template>
 
 <script setup>
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import { useAuth } from '../composables/useAuth.js'
+import WaitlistForm from './WaitlistForm.vue'
 
 const { isAuthenticated, userTier } = useAuth()
 
@@ -102,6 +105,8 @@ const PRICE_SUFFIX = { monthly: '/mo', annual: '/yr' }
 // disabled until then. Remove a tier from this list to make its button live.
 const COMING_SOON = ['basic', 'plus']
 
+const hasComingSoon = computed(() => COMING_SOON.length > 0)
+
 function isComingSoon(tier) {
     return COMING_SOON.includes(tier)
 }

resources/js/components/WaitlistForm.vue

@@ -0,0 +1,67 @@
+<template>
+    <div class="max-w-2xl mx-auto mt-12">
+        <div class="bg-white border border-zinc-300 rounded-3xl p-8 text-center">
+            <template v-if="success">
+                <div class="flex flex-col items-center gap-3">
+                    <span class="inline-flex items-center justify-center w-12 h-12 rounded-full bg-accent/10 text-accent">
+                        <iconify-icon class="text-2xl" icon="lucide:check"></iconify-icon>
+                    </span>
+                    <h3 class="text-xl font-bold font-display text-zinc-800">You're on the list</h3>
+                    <p class="text-zinc-500 text-sm">We'll email you the moment price alerts go live.</p>
+                </div>
+            </template>
+
+            <template v-else>
+                <h3 class="text-xl font-bold font-display text-zinc-800 mb-1">Want in when alerts launch?</h3>
+                <p class="text-zinc-500 text-sm mb-6">Leave your details and we'll let you know the day alerts go live.</p>
+
+                <form class="flex flex-col sm:flex-row gap-3" @submit.prevent="onSubmit">
+                    <input
+                        v-model.trim="name"
+                        type="text"
+                        autocomplete="name"
+                        placeholder="Your name"
+                        required
+                        :disabled="loading"
+                        class="flex-1 px-4 py-3 border border-zinc-300 rounded-xl text-sm focus:outline-none focus:ring-2 focus:ring-accent disabled:opacity-60"
+                    >
+                    <input
+                        v-model.trim="email"
+                        type="email"
+                        autocomplete="email"
+                        placeholder="you@example.com"
+                        required
+                        :disabled="loading"
+                        class="flex-1 px-4 py-3 border border-zinc-300 rounded-xl text-sm focus:outline-none focus:ring-2 focus:ring-accent disabled:opacity-60"
+                    >
+                    <button
+                        type="submit"
+                        :disabled="loading"
+                        class="px-6 py-3 bg-accent text-white rounded-xl font-bold text-sm shadow-lg hover:bg-primary-dark transition-all disabled:opacity-60 disabled:cursor-not-allowed whitespace-nowrap"
+                    >
+                        {{ loading ? 'Joining…' : 'Notify me' }}
+                    </button>
+                </form>
+
+                <p v-if="error" class="text-red-600 text-sm mt-3 text-left">{{ error }}</p>
+            </template>
+        </div>
+    </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { useWaitlist } from '../composables/useWaitlist.js'
+
+const props = defineProps({
+    source: { type: String, default: 'pricing' },
+})
+
+const name = ref('')
+const email = ref('')
+const { loading, success, error, submit } = useWaitlist()
+
+function onSubmit() {
+    submit(name.value, email.value, props.source)
+}
+</script>

resources/js/composables/useWaitlist.js

@@ -0,0 +1,31 @@
+import { ref } from 'vue'
+import api from '../axios.js'
+
+export function useWaitlist() {
+    const loading = ref(false)
+    const success = ref(false)
+    const error = ref(null)
+
+    async function submit(name, email, source = null) {
+        loading.value = true
+        error.value = null
+        try {
+            await api.post('/waitlist', {
+                name,
+                email,
+                source,
+                referrer: document.referrer || null,
+            })
+            success.value = true
+        } catch (e) {
+            const fieldErrors = e.response?.data?.errors
+            error.value = fieldErrors
+                ? Object.values(fieldErrors)[0][0]
+                : (e.response?.data?.message || 'Something went wrong — please try again.')
+        } finally {
+            loading.value = false
+        }
+    }
+
+    return { loading, success, error, submit }
+}

routes/api.php

@@ -5,6 +5,7 @@ use App\Http\Controllers\Api\AuthController;
 use App\Http\Controllers\Api\StationController;
 use App\Http\Controllers\Api\StatsController;
 use App\Http\Controllers\Api\UserController;
+use App\Http\Controllers\Api\WaitlistController;
 use App\Http\Middleware\VerifyApiKey;
 use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Facades\Route;
@@ -22,6 +23,9 @@ Route::get('/fuel-types', function () {
 
 Route::get('/stats/live', [StatsController::class, 'live']);
 
+// Feature-launch waitlist signup (public, separate from registered users)
+Route::post('/waitlist', [WaitlistController::class, 'store'])->middleware('throttle:10,1');
+
 // Protected endpoints (API key required)
 Route::middleware(['throttle:60,1', VerifyApiKey::class])->group(function (): void {
     Route::get('/stations', [StationController::class, 'index']);

tests/Feature/Admin/WaitlistSubscriberResourceTest.php

@@ -0,0 +1,31 @@
+<?php
+
+use App\Filament\Resources\WaitlistSubscriberResource\Pages\ListWaitlistSubscribers;
+use App\Models\User;
+use App\Models\WaitlistSubscriber;
+use Livewire\Livewire;
+
+beforeEach(function () {
+    $this->actingAs(User::factory()->admin()->create());
+});
+
+it('lists waitlist subscribers', function () {
+    $subscribers = WaitlistSubscriber::factory()->count(3)->create();
+
+    Livewire::test(ListWaitlistSubscribers::class)
+        ->assertOk()
+        ->assertCanSeeTableRecords($subscribers);
+});
+
+it('exposes a CSV export header action', function () {
+    Livewire::test(ListWaitlistSubscribers::class)
+        ->assertActionExists('export');
+});
+
+it('exports a CSV download when the action runs against real subscribers', function () {
+    WaitlistSubscriber::factory()->count(2)->create();
+
+    Livewire::test(ListWaitlistSubscribers::class)
+        ->callAction('export')
+        ->assertFileDownloaded('waitlist.csv');
+});

tests/Feature/Api/WaitlistTest.php

@@ -0,0 +1,64 @@
+<?php
+
+use App\Models\WaitlistSubscriber;
+
+it('stores a subscriber and returns 201', function () {
+    $response = $this->postJson('/api/waitlist', [
+        'name' => 'Ada Lovelace',
+        'email' => 'ada@example.com',
+    ]);
+
+    $response->assertCreated()
+        ->assertJsonStructure(['message']);
+
+    $this->assertDatabaseHas('waitlist_subscribers', [
+        'name' => 'Ada Lovelace',
+        'email' => 'ada@example.com',
+    ]);
+});
+
+it('treats a duplicate email as success without creating a second row', function () {
+    WaitlistSubscriber::factory()->create(['email' => 'ada@example.com']);
+
+    $this->postJson('/api/waitlist', [
+        'name' => 'Someone Else',
+        'email' => 'ada@example.com',
+    ])->assertCreated();
+
+    expect(WaitlistSubscriber::where('email', 'ada@example.com')->count())->toBe(1);
+});
+
+it('stores the source and referrer sent with the request', function () {
+    $this->postJson('/api/waitlist', [
+        'name' => 'Ada Lovelace',
+        'email' => 'ada@example.com',
+        'source' => 'pricing',
+        'referrer' => 'https://duckduckgo.com/',
+    ])->assertCreated();
+
+    $this->assertDatabaseHas('waitlist_subscribers', [
+        'email' => 'ada@example.com',
+        'source' => 'pricing',
+        'referrer' => 'https://duckduckgo.com/',
+    ]);
+});
+
+it('requires a name', function () {
+    $this->postJson('/api/waitlist', [
+        'email' => 'ada@example.com',
+    ])->assertStatus(422)->assertJsonValidationErrors('name');
+});
+
+it('rejects an invalid email', function () {
+    $this->postJson('/api/waitlist', [
+        'name' => 'Ada Lovelace',
+        'email' => 'not-an-email',
+    ])->assertStatus(422)->assertJsonValidationErrors('email');
+});
+
+it('throttles the endpoint', function () {
+    $route = collect(app('router')->getRoutes())
+        ->first(fn ($route) => $route->uri() === 'api/waitlist' && in_array('POST', $route->methods(), true));
+
+    expect($route?->gatherMiddleware())->toContain('throttle:10,1');
+});

tests/Unit/Services/WaitlistServiceTest.php

@@ -0,0 +1,47 @@
+<?php
+
+use App\Models\WaitlistSubscriber;
+use App\Services\WaitlistService;
+
+it('normalises the email to trimmed lowercase before storing', function () {
+    $subscriber = app(WaitlistService::class)->subscribe('Ada Lovelace', '  Ada@Example.COM ');
+
+    expect($subscriber->email)->toBe('ada@example.com')
+        ->and($subscriber->name)->toBe('Ada Lovelace');
+
+    $this->assertDatabaseHas('waitlist_subscribers', ['email' => 'ada@example.com']);
+});
+
+it('is idempotent — re-subscribing the same email keeps a single row and returns the original', function () {
+    $service = app(WaitlistService::class);
+
+    $first = $service->subscribe('Ada', 'ada@example.com');
+    $second = $service->subscribe('Different Name', 'ADA@example.com');
+
+    expect($second->id)->toBe($first->id)
+        ->and($second->name)->toBe('Ada');
+
+    expect(WaitlistSubscriber::where('email', 'ada@example.com')->count())->toBe(1);
+});
+
+it('stores the source and referrer on a new subscriber', function () {
+    $subscriber = app(WaitlistService::class)->subscribe(
+        'Ada',
+        'ada@example.com',
+        source: 'pricing',
+        referrer: 'https://duckduckgo.com/',
+    );
+
+    expect($subscriber->source)->toBe('pricing')
+        ->and($subscriber->referrer)->toBe('https://duckduckgo.com/');
+});
+
+it('preserves the original meta when an existing email re-subscribes', function () {
+    $service = app(WaitlistService::class);
+
+    $service->subscribe('Ada', 'ada@example.com', source: 'pricing', referrer: 'https://a.test');
+    $second = $service->subscribe('Ada', 'ada@example.com', source: 'home', referrer: 'https://b.test');
+
+    expect($second->source)->toBe('pricing')
+        ->and($second->referrer)->toBe('https://a.test');
+});