Rewrite chess-api in TypeScript with clean game API + timed clocks

.env.example

@@ -0,0 +1,7 @@
+DATABASE_URL=postgres://user:pass@host:5432/chess
+GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+STRIPE_PRICE_PRO=price_...
+APP_URL=http://localhost:3000
+PORT=3000

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  api-build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install API deps
+        run: npm ci
+
+      - name: Build API
+        run: npm run build
+
+      - name: Test API
+        run: npm test
+
+  web-build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install web deps
+        run: npm ci
+
+      - name: Build web
+        run: npm run build

.gitignore

@@ -1,2 +1,4 @@
 node_modules
 .env
+dist
+*.log

PLAN.md

@@ -0,0 +1,75 @@
+# CHESS API SAAS PLAN (Execution Checklist)
+
+## Goal
+Ship a production-ready SaaS chess API where users can sign in, create API keys, and build apps without their own backend.
+
+## Current State (done)
+- [x] NestJS modular rewrite (auth/users/chess/database/health)
+- [x] Postgres + Drizzle schemas
+- [x] Google auth endpoint
+- [x] API key create/list/revoke
+- [x] Core chess routes (create/get/delete/moves/ai/resign)
+- [x] Timed games support
+- [x] DTO coverage + module tests + engine tests
+- [x] SaaS landing/docs/login/dashboard scaffolding + wiring
+- [x] Basic plan model + free-tier API key limits
+
+## Remaining (must finish)
+
+### 1) Billing + Entitlements (Stripe)
+- [x] Stripe customer creation on first paid action
+- [x] Checkout session endpoint
+- [x] Billing portal endpoint
+- [x] Webhook handler (subscription created/updated/canceled)
+- [x] Persist plan tier/status in `plans`
+- [x] Enforce plan limits:
+  - [x] free: low RPM + low monthly requests + key cap
+  - [x] pro: higher quotas
+
+### 2) Production API hardening
+- [x] Centralized exception filter + error shape
+- [x] Request logging middleware with requestId
+- [x] API key rate limit per key (not only global)
+- [x] Pagination DTOs + list endpoints:
+  - [x] `GET /games` with filters/status/mode
+  - [x] `GET /players` (or profile-scoped player listing)
+- [x] Ownership checks on all mutable resources
+
+### 3) Data model completion
+- [x] `players` table (profile for app users)
+- [x] `game_players` table (white/black participants)
+- [x] Optional metadata fields for external app IDs
+
+### 4) Docs + Developer onboarding
+- [x] “Get key in 60 seconds” flow docs
+- [x] Copy-paste SDK-style snippets (JS/TS + curl)
+- [x] Plan limits docs + upgrade path
+- [x] Error code catalog
+
+### 5) Ops + deployment
+- [x] docker-compose for local Postgres + app
+- [x] env validation at boot
+- [x] CI workflow (build + test)
+- [x] Vercel deployment files/config
+- [x] staging verification script
+
+### 6) QA checklist (before STG signoff)
+Blocked pending staging credentials/env:
+- `API_BASE_URL`
+- one of: `GOOGLE_ID_TOKEN` or `ACCESS_TOKEN`
+- `STRIPE_TEST_PRICE_ID` (optional for billing endpoint verification; or configured `STRIPE_PRICE_PRO` on staging)
+- `STRIPE_WEBHOOK_SECRET` + `STRIPE_CUSTOMER_ID` + `USER_ID` (for webhook transition script)
+
+- [ ] Google login works
+- [ ] API key lifecycle works
+- [ ] Game flow works (create->move->ai->resign)
+- [ ] Clock timeout works
+- [ ] Free-tier limits enforced
+- [ ] Upgrade to pro updates limits
+- [ ] Stripe webhook updates entitlements (ready to verify via `scripts/staging-webhook-verify.sh`)
+- [ ] Docs examples execute successfully
+
+## Work Rules
+- Keep scope strictly to SaaS chess API.
+- No extra features unless directly required for reliability, billing, or developer onboarding.
+- Commit in small, verifiable increments.

README.md

@@ -1,15 +1,188 @@
-# ♟️ Chess API ♟️
-API for playing chess and highscores storing. Api could be easily used to implement a multiplayer room based chess game, because every instance of a game initilizes new unique game_id.
-* ### [API Documentation](https://documenter.getpostman.com/view/1741165/chess-api/7Lof2bk#intro)
+# chess-api (NestJS rewrite)
 
-## Feautures:
+Proper modular architecture with NestJS:
 
-* Player vs. Player game mode
-* Player vs. Computer game mode
-* Highscores data storing
+- `AuthModule` (Google login + sessions)
+- `UsersModule` (API key management)
+- `ChessModule` (game lifecycle, clocks, PvP/PvE)
+- `DatabaseModule` (Postgres + Drizzle)
+- `HealthModule` (root/docs)
 
+## Tech
+- NestJS
+- PostgreSQL
+- Drizzle ORM
+- Google OAuth ID token verification
+- chess.js + chess-ai-kong
 
-## Built With
+## Env
+```env
+DATABASE_URL=postgres://...
+GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+STRIPE_PRICE_PRO=price_...
+APP_URL=http://localhost:3000
+PORT=3000
+```
 
-* [Chess.js](https://github.com/jhlywa/chess.js)
-* [ChessCorp Artificial Intelligence: Kong](https://www.npmjs.com/package/chess-ai-kong)
+## Run API
+```bash
+npm install
+npm run dev
+```
+
+## Staging verification script
+```bash
+API_BASE_URL=https://stg-api.example.com \
+GOOGLE_ID_TOKEN=<google_id_token> \
+bash scripts/staging-verify.sh
+```
+
+## QA checklist runner (staging)
+```bash
+API_BASE_URL=https://stg-api.example.com \
+GOOGLE_ID_TOKEN=<google_id_token> \
+bash scripts/qa-checklist.sh
+```
+(Or provide `ACCESS_TOKEN` directly to skip login bootstrap.)
+
+## Stripe webhook transition verifier (staging)
+Use this after you have a real staged user + Stripe customer id.
+
+```bash
+API_BASE_URL=https://stg-api.example.com \
+STRIPE_WEBHOOK_SECRET=whsec_xxx \
+STRIPE_CUSTOMER_ID=cus_xxx \
+USER_ID=<app_user_id> \
+bash scripts/staging-webhook-verify.sh
+```
+
+Optional billing checks:
+```bash
+API_BASE_URL=https://stg-api.example.com \
+GOOGLE_ID_TOKEN=<google_id_token> \
+STRIPE_TEST_PRICE_ID=price_xxx \
+bash scripts/qa-checklist.sh
+```
+
+## Landing page + docs + login + dashboard (shadcn-style UI)
+A separate Next.js app lives in `web/` and is wired to the API.
+
+```bash
+cd web
+cp .env.example .env.local
+npm install
+npm run dev
+```
+
+### Vercel deploy (web)
+`web/vercel.json` is included for Vercel deployment.
+
+Required Vercel project env vars:
+- `NEXT_PUBLIC_API_BASE_URL`
+- `NEXT_PUBLIC_GOOGLE_CLIENT_ID`
+
+Suggested project root in Vercel: `web/`
+
+## Auth routes
+- `POST /auth/google` with `{ idToken }`
+- `GET /me` (Bearer session token)
+- `GET /me/api-keys`
+- `POST /me/api-keys`
+- `DELETE /me/api-keys/:id`
+
+## Chess routes (require `x-api-key`)
+- `GET /games`
+- `GET /games/players`
+- `POST /games/players`
+- `POST /games/:id/players`
+- `POST /games`
+- `GET /games/:id`
+- `DELETE /games/:id`
+- `GET /games/:id/moves`
+- `POST /games/:id/moves`
+- `POST /games/:id/ai-move`
+- `POST /games/:id/resign`
+
+## Get key in 60 seconds
+1. **Sign in** via `POST /auth/google` with your Google ID token.
+2. **Save bearer token** from `accessToken` in response.
+3. **Create API key** via `POST /me/api-keys` using bearer auth.
+4. **Call chess API** with `x-api-key: <returned apiKey>`.
+
+Quick example:
+```bash
+# 1) Google login
+curl -s -X POST http://localhost:3000/auth/google \
+  -H "content-type: application/json" \
+  -d '{"idToken":"<google-id-token>"}'
+
+# 2) Create API key (replace $ACCESS_TOKEN)
+curl -s -X POST http://localhost:3000/me/api-keys \
+  -H "authorization: Bearer $ACCESS_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"name":"quickstart"}'
+
+# 3) Create a game (replace $API_KEY)
+curl -s -X POST http://localhost:3000/games \
+  -H "x-api-key: $API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"mode":"pve","aiColor":"b"}'
+```
+
+## Plan limits + upgrade path
+
+### Free
+- API keys: **2 active keys**
+- Rate limit: **30 requests/minute** per API key
+- Monthly quota: **10,000 requests** per account
+
+### Pro
+- API keys: **20 active keys**
+- Rate limit: **300 requests/minute** per API key
+- Monthly quota: **1,000,000 requests** per account
+
+### Upgrade
+1. Create checkout session: `POST /billing/checkout-session`
+2. Redirect user to returned Stripe URL
+3. Stripe webhook updates plan to `pro` when subscription is active
+4. User can manage billing via `POST /billing/portal-session`
+
+Minimal checkout call:
+```bash
+curl -s -X POST http://localhost:3000/billing/checkout-session \
+  -H "authorization: Bearer $ACCESS_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{}'
+```
+
+## Error code catalog
+All API errors use a consistent shape:
+
+```json
+{
+  "error": {
+    "statusCode": 400,
+    "code": "Bad Request",
+    "message": "Human-readable message"
+  },
+  "path": "/games",
+  "timestamp": "2026-02-22T22:00:00.000Z"
+}
+```
+
+Common errors:
+- `401 Unauthorized`
+  - Missing/invalid bearer session (`/me`, `/billing/*`)
+  - Missing/invalid `x-api-key` (`/games*`)
+- `404 Not Found`
+  - Game or player not found / not owned by caller
+- `429 Too Many Requests`
+  - API key RPM exceeded for current plan
+  - Monthly request quota exceeded for current plan
+- `400 Bad Request`
+  - Validation failures (DTO constraints)
+  - Missing billing config (e.g. Stripe price)
+- `500 Internal Server Error`
+  - Unhandled server-side failure