api-contracts-and-zod-validation

# API Contracts and Zod Validation

Generate Zod schemas with TypeScript type inference for forms, API routes, and Server Actions. Validate inputs in Server Actions or route handlers with runtime type checking.

## Core Capabilities

### 1. Generate Zod Schemas from TypeScript Types

When creating API contracts or form validations:

- Analyze existing TypeScript interfaces or types
- Generate equivalent Zod schemas with proper validation rules
- Ensure bidirectional type compatibility (Zod -> TypeScript)
- Use `z.infer<typeof schema>` for automatic type inference

### 2. Form Validation Schemas

To create form validation with Zod:

- Generate schemas for React Hook Form, Formik, or native forms
- Include field-level validation rules (min/max length, regex, custom validators)
- Support nested objects, arrays, and complex data structures
- Provide helpful error messages for validation failures
- Use `references/zod_patterns.md` for common validation patterns

### 3. API Route and Server Action Validation

To add validation to API endpoints or Server Actions:

- Wrap handler logic with schema validation using `.parse()` or `.safeParse()`
- Return typed errors for validation failures
- Generate request/response schemas for API contracts
- Validate query parameters, body payloads, and route parameters
- Ensure type safety between client and server code

### 4. Schema Generation Script

Use `scripts/generate_zod_schema.py` to automate schema generation:

```bash
python scripts/generate_zod_schema.py --input types/entities.ts --output schemas/entities.ts
```

The script:
- Parses TypeScript interfaces/types
- Generates Zod schemas with appropriate validators
- Preserves JSDoc comments as descriptions
- Handles common patterns (optional fields, unions, enums)

## Resource Files

### scripts/generate_zod_schema.py
Automated TypeScript-to-Zod schema generator. Parses TypeScript AST and generates equivalent Zod schemas.

### references/zod_patterns.md
Common Zod validation pat