docs(waitlist): add README.md

[amondnet]

Summary

• Add comprehensive README for the @please-auth/waitlist package

Changes

• Documents installation and setup
• Covers server-side and client-side usage
• Details configuration options
• Documents API endpoints, database schema, and error codes
• Explains how the waitlist plugin works internally

Test Plan

• Verify README renders correctly on GitHub
• Check all code examples are accurate
• Confirm links and formatting are correct

---

Summary by cubic

Add a comprehensive README for the @please-auth/waitlist package, covering install, server/client setup, config, public/admin APIs, DB schema, error codes, and how the plugin works. Also update the root README.md to link package entries to their #readme anchors (for @please-auth/waitlist and @please-auth/firestore) to improve navigation.

^{Written for commit d822864. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 1 file

Architecture diagram

sequenceDiagram
    participant Client as User / Auth Client
    participant Auth as Auth Server (Waitlist Plugin)
    participant DB as Database
    participant Email as Email Service

    Note over Client, DB: Waitlist Onboarding Flow
    
    Client->>Auth: NEW: POST /waitlist/join (email)
    Auth->>DB: Create waitlist entry (status: pending)
    DB-->>Auth: Record + lookupToken
    Auth-->>Client: 200 OK (lookupToken)

    Note over Auth, Email: Admin Approval Flow

    Auth->>DB: CHANGED: Update status to 'approved'
    Auth->>Auth: NEW: Generate inviteCode & expiry
    Auth->>Email: NEW: sendInviteEmail()
    Email-->>Client: Invite Code Notification

    Note over Client, DB: Sign-up Interception Flow

    Client->>Auth: POST /sign-up/email (or OAuth/Magic-link)
    Auth->>Auth: NEW: Intercept Path (Middleware)
    Auth->>DB: Query waitlist by email
    
    alt Entry Not Found OR Not Approved
        DB-->>Auth: No valid entry
        Auth-->>Client: 403 Forbidden (NOT_APPROVED)
    else Entry Approved
        DB-->>Auth: Approved entry + inviteCode
        
        opt requireInviteCode: true
            Auth->>Auth: NEW: Verify inviteCode vs request body
        end
        
        Auth->>DB: Create User (via database hook)
        Auth->>DB: CHANGED: Update status to 'registered'
        DB-->>Auth: Success
        Auth-->>Client: 200 OK (Session Created)
    end

    Note over Client, Auth: Status Polling (Optional)
    Client->>Auth: GET /waitlist/status?token=<lookupToken>
    Auth->>DB: Fetch entry
    DB-->>Auth: Current status
    Auth-->>Client: JSON Status Object

Loading