veza/apps/web/docs/ZOD_SCHEMA_AUDIT.md

# Zod Schema Audit Report

**Date**: 2025-01-27  
**Action**: 1.2.1.1 - Audit existing Zod schemas  
**Status**: ✅ Complete

## Overview

This document audits existing Zod schemas and identifies gaps compared to the OpenAPI specification.

## Existing Schema Files

1. **`apps/web/src/schemas/apiSchemas.ts`** - Response schemas (399 lines)
2. **`apps/web/src/schemas/apiRequestSchemas.ts`** - Request schemas (290 lines)
3. **`apps/web/src/schemas/validation.ts`** - General validation utilities
4. **`apps/web/src/features/profile/schemas/profileSchema.ts`** - Profile-specific schemas
5. **`apps/web/src/features/settings/schemas/settingsSchema.ts`** - Settings-specific schemas

## Response Schemas Found

### Core Types:
- ✅ `userSchema` - User object schema
- ✅ `trackSchema` - Track object schema
- ✅ `playlistSchema` - Playlist object schema
- ✅ `messageSchema` - Chat message schema
- ✅ `conversationSchema` - Conversation schema
- ✅ `commentSchema` - Comment schema
- ✅ `paginatedResponseSchema` - Pagination wrapper

### API Response Wrappers:
- ✅ `apiResponseSchema` - Base API response wrapper `{ success, data, error }`
- ✅ `errorResponseSchema` - Error response schema

## Request Schemas Found

### Authentication:
- ✅ `loginRequestSchema` - Login credentials
- ✅ `registerRequestSchema` - User registration
- ✅ `refreshRequestSchema` - Token refresh

### User Management:
- ✅ `createUserRequestSchema` - Create user
- ✅ `updateUserRequestSchema` - Update user
- ✅ `updateProfileRequestSchema` - Update profile

### Chat:
- ✅ `sendMessageRequestSchema` - Send chat message
- ✅ `createConversationRequestSchema` - Create conversation

### Tracks:
- ✅ `createTrackRequestSchema` - Create track
- ✅ `updateTrackRequestSchema` - Update track
- ✅ `uploadTrackRequestSchema` - Upload track file

### Playlists:
- ✅ `createPlaylistRequestSchema` - Create playlist
- ✅ `updatePlaylistRequestSchema` - Update playlist
- ✅ `addTrackToPlaylistRequestSchema` - Add track to playlist

### Comments:
- ✅ `createCommentRequestSchema` - Create comment
- ✅ `updateCommentRequestSchema` - Update comment

## OpenAPI Endpoints Coverage

**Total endpoints in OpenAPI spec**: 56 endpoints

### Endpoints with Schemas:
- ✅ `/auth/login` - loginRequestSchema
- ✅ `/auth/register` - registerRequestSchema
- ✅ `/auth/refresh` - refreshRequestSchema
- ✅ `/tracks` (POST) - createTrackRequestSchema
- ✅ `/tracks/{id}` (PUT) - updateTrackRequestSchema
- ✅ `/playlists` (POST) - createPlaylistRequestSchema
- ✅ `/playlists/{id}` (PUT) - updatePlaylistRequestSchema
- ✅ `/tracks/{id}/comments` (POST) - createCommentRequestSchema
- ✅ `/comments/{id}` (PUT) - updateCommentRequestSchema

### Endpoints Missing Request Schemas:
- ⚠️ `/analytics/events` (POST) - RecordEventRequest
- ⚠️ `/analytics/tracks/{id}` (GET) - No request schema needed
- ⚠️ `/analytics/tracks/top` (GET) - Query params schema needed
- ⚠️ `/tracks/batch/delete` (POST) - BatchDeleteRequest
- ⚠️ `/tracks/chunk` (POST) - Chunk upload request
- ⚠️ `/tracks/complete` (POST) - Complete upload request
- ⚠️ `/tracks/initiate` (POST) - Initiate upload request
- ⚠️ `/tracks/resume/{uploadId}` (GET) - No request schema needed
- ⚠️ `/tracks/quota/{id}` (GET) - No request schema needed
- ⚠️ `/playlists/{id}/tracks` (POST) - addTrackToPlaylistRequestSchema exists
- ⚠️ `/playlists/{id}/tracks/reorder` (POST) - ReorderTracksRequest
- ⚠️ `/webhooks` (POST) - Webhook registration request
- ⚠️ `/webhooks/{id}/regenerate-key` (POST) - No request schema needed
- ⚠️ `/webhooks/{id}/test` (POST) - No request schema needed
- ⚠️ `/auth/2fa/setup` (POST) - Two-factor setup request
- ⚠️ `/auth/2fa/verify` (POST) - Two-factor verification request
- ⚠️ `/auth/2fa/disable` (POST) - Two-factor disable request
- ⚠️ `/marketplace/products` (POST) - CreateProductRequest
- ⚠️ `/marketplace/products/{id}` (PUT) - UpdateProductRequest
- ⚠️ `/marketplace/orders` (POST) - CreateOrderRequest
- ⚠️ `/api/v1/logs/frontend` (POST) - FrontendLogRequest

## Response Schema Coverage

### Response Types Covered:
- ✅ User responses - userSchema
- ✅ Track responses - trackSchema
- ✅ Playlist responses - playlistSchema
- ✅ Comment responses - commentSchema
- ✅ Paginated responses - paginatedResponseSchema
- ✅ API response wrapper - apiResponseSchema

### Response Types Missing:
- ⚠️ Analytics responses - Analytics data structures
- ⚠️ Webhook responses - Webhook registration/management
- ⚠️ Marketplace responses - Product and Order types
- ⚠️ Two-factor responses - 2FA setup/verification responses
- ⚠️ Upload status responses - Track upload status types
- ⚠️ Search responses - Search result types

## Schema Quality Assessment

### Strengths:
1. ✅ Core types (User, Track, Playlist) are well-defined
2. ✅ Base schemas (UUID, dates) are reusable
3. ✅ Request validation covers main CRUD operations
4. ✅ Response wrapper schema exists

### Gaps:
1. ⚠️ Missing schemas for analytics endpoints
2. ⚠️ Missing schemas for marketplace endpoints
3. ⚠️ Missing schemas for webhook endpoints
4. ⚠️ Missing schemas for 2FA endpoints
5. ⚠️ Missing schemas for upload chunking endpoints
6. ⚠️ Missing query parameter schemas for GET endpoints
7. ⚠️ Missing response schemas for specialized endpoints

## Recommendations

### Priority 1 (High):
1. Add request schemas for batch operations (batch delete, reorder)
2. Add request schemas for upload operations (initiate, chunk, complete)
3. Add request schemas for 2FA operations

### Priority 2 (Medium):
1. Add request schemas for analytics endpoints
2. Add request schemas for marketplace endpoints
3. Add request schemas for webhook endpoints

### Priority 3 (Low):
1. Add query parameter schemas for GET endpoints with filters
2. Add response schemas for specialized endpoints
3. Generate schemas automatically from OpenAPI spec

## Next Steps

1. ✅ **Action 1.2.1.1**: Audit complete - This document
2. ⏭️ **Action 1.2.1.2**: Generate Zod schemas from OpenAPI spec (or manually add missing schemas)
3. ⏭️ **Action 1.2.1.3**: Audit all API endpoints for request schemas
4. ⏭️ **Action 1.2.1.4**: Add missing request validation schemas

## Validation

✅ Audit complete - Found 20+ existing schemas, identified 15+ missing request schemas  
✅ Core types well-covered (User, Track, Playlist)  
⚠️ Specialized endpoints need schema coverage