pragma-stack/frontend/scripts/sync-msw-with-openapi.md

Keeping MSW Handlers Synced with OpenAPI Spec

Problem

MSW handlers can drift out of sync with the backend API as it evolves.

Solution Options

Option 1: Use openapi-msw (Recommended)

Install the package that auto-generates MSW handlers from OpenAPI:

bun install --save-dev openapi-msw

Then create a generation script:

// scripts/generate-msw-handlers.ts
import { generateMockHandlers } from 'openapi-msw';
import fs from 'fs';

async function generate() {
  const spec = JSON.parse(fs.readFileSync('/tmp/openapi.json', 'utf-8'));

  const handlers = generateMockHandlers(spec, {
    baseUrl: 'http://localhost:8000',
  });

  fs.writeFileSync('src/mocks/handlers/generated.ts', handlers);
}

generate();

Option 2: Manual Sync Checklist

When you add/change backend endpoints:

1. Update Backend → Make API changes
2. Generate Frontend Client → bun run generate:api
3. Update MSW Handlers → Edit src/mocks/handlers/*.ts
4. Test Demo Mode → NEXT_PUBLIC_DEMO_MODE=true bun run dev

Option 3: Automated with Script Hook

Add to package.json:

{
  "scripts": {
    "generate:api": "./scripts/generate-api-client.sh && bun run sync:msw",
    "sync:msw": "echo '⚠️  Don't forget to update MSW handlers in src/mocks/handlers/'"
  }
}

Current Coverage

Our MSW handlers currently cover:

Auth Endpoints:

• POST /api/v1/auth/register
• POST /api/v1/auth/login
• POST /api/v1/auth/refresh
• POST /api/v1/auth/logout
• POST /api/v1/auth/logout-all
• POST /api/v1/auth/password-reset
• POST /api/v1/auth/password-reset/confirm
• POST /api/v1/auth/change-password

User Endpoints:

• GET /api/v1/users/me
• PATCH /api/v1/users/me
• DELETE /api/v1/users/me
• GET /api/v1/users/:id
• GET /api/v1/users
• GET /api/v1/organizations/me
• GET /api/v1/sessions
• DELETE /api/v1/sessions/:id

Admin Endpoints:

• GET /api/v1/admin/stats
• GET /api/v1/admin/users
• GET /api/v1/admin/users/:id
• POST /api/v1/admin/users
• PATCH /api/v1/admin/users/:id
• DELETE /api/v1/admin/users/:id
• POST /api/v1/admin/users/bulk
• GET /api/v1/admin/organizations
• GET /api/v1/admin/organizations/:id
• GET /api/v1/admin/organizations/:id/members
• GET /api/v1/admin/sessions

Quick Validation

To check if MSW is missing handlers:

1. Start demo mode: NEXT_PUBLIC_DEMO_MODE=true bun run dev
2. Open browser console
3. Look for [MSW] Warning: intercepted a request without a matching request handler
4. Add missing handlers to appropriate file in src/mocks/handlers/

Best Practices

1. Keep handlers simple - Return happy path responses by default
2. Match backend schemas - Use generated TypeScript types
3. Realistic delays - Use await delay(300) for UX testing
4. Document passwords - Make demo credentials obvious
5. Test regularly - Run demo mode after API changes