# OpenAPI TypeScript Generation

This project now supports automatic TypeScript type generation from the FastAPI server's Pydantic models using OpenAPI schema generation.

## Overview

The implementation follows the "OpenAPI Schema Generation (Recommended for FastAPI)" approach:

1. **Server-side**: FastAPI automatically generates OpenAPI schema from Pydantic models
2. **Generation**: Python script extracts the schema and saves it as JSON
3. **TypeScript**: `openapi-typescript` converts the schema to TypeScript types
4. **Client**: Typed API client provides type-safe server communication

## Generated Files

- `client/openapi-schema.json` - OpenAPI schema extracted from FastAPI
- `client/src/api-types.ts` - TypeScript interfaces generated from OpenAPI schema
- `client/src/api-client.ts` - Typed API client with convenience methods

## How It Works

### 1. Schema Generation
The `server/generate_schema_simple.py` script:
- Imports the FastAPI app from `main.py`
- Extracts the OpenAPI schema using `app.openapi()`
- Saves the schema as JSON in `client/openapi-schema.json`

### 2. TypeScript Generation
The `openapi-typescript` package:
- Reads the OpenAPI schema JSON
- Generates TypeScript interfaces in `client/src/api-types.ts`
- Creates type-safe definitions for all Pydantic models

### 3. API Client
The `client/src/api-client.ts` file provides:
- Type-safe API client class
- Convenience functions for each endpoint
- Proper error handling with custom `ApiError` class
- Re-exported types for easy importing

## Usage in React Components

```typescript
import { apiClient, adminApi, healthApi, lobbiesApi, sessionsApi } from './api-client';
import type { LobbyModel, SessionModel, AdminSetPassword } from './api-client';

// Using the convenience APIs
const healthStatus = await healthApi.check();
const lobbies = await lobbiesApi.getAll();
const session = await sessionsApi.getCurrent();

// Using the main client
const adminNames = await apiClient.adminListNames();

// With type safety for request data
const passwordData: AdminSetPassword = {
  name: "admin",
  password: "newpassword"
};
const result = await adminApi.setPassword(passwordData);

// Type-safe lobby creation
const lobbyRequest: LobbyCreateRequest = {
  type: "lobby_create",
  data: {
    name: "My Lobby",
    private: false
  }
};
const newLobby = await sessionsApi.createLobby("session-id", lobbyRequest);
```

## Regenerating Types

### Manual Generation
```bash
# Generate schema from server
docker compose exec server uv run python3 generate_schema_simple.py

# Generate TypeScript types
docker compose exec client npx openapi-typescript openapi-schema.json -o src/api-types.ts

# Type check
docker compose exec client npm run type-check
```

### Automated Generation
```bash
# Run the comprehensive generation script
./generate-ts-types.sh
```

### NPM Scripts (in frontend container)
```bash
# Generate just the schema
npm run generate-schema

# Generate just the TypeScript types (requires schema to exist)
npm run generate-types

# Generate both schema and types
npm run generate-api-types
```

## Development Workflow

1. **Modify Pydantic models** in `shared/models.py`
2. **Regenerate types** using one of the methods above
3. **Update React components** to use the new types
4. **Type check** to ensure everything compiles

## Benefits

- ✅ **Type Safety**: Full TypeScript type checking for API requests/responses
- ✅ **Auto-completion**: IDE support with auto-complete for API methods and data structures
- ✅ **Error Prevention**: Catch type mismatches at compile time
- ✅ **Documentation**: Self-documenting API with TypeScript interfaces
- ✅ **Sync Guarantee**: Types are always in sync with server models
- ✅ **Refactoring Safety**: IDE can safely refactor across frontend/backend

## File Structure

```
server/
├── main.py                    # FastAPI app with Pydantic models
├── generate_schema_simple.py  # Schema extraction script
└── generate_api_client.py     # Enhanced generator (backup)

shared/
└── models.py                  # Pydantic models (source of truth)

client/
├── openapi-schema.json        # Generated OpenAPI schema
├── package.json              # Updated with openapi-typescript dependency
└── src/
    ├── api-types.ts          # Generated TypeScript interfaces
    └── api-client.ts         # Typed API client
```

## Troubleshooting

### Container Issues
If the frontend container has dependency conflicts:
```bash
# Rebuild the frontend container
docker compose build client
docker compose up -d client
```

### TypeScript Errors
Ensure the generated types are up to date:
```bash
./generate-ts-types.sh
```

### Module Not Found Errors
Check that the volume mounts are working correctly and files are synced between host and container.

## API Evolution Detection

The system now includes automatic detection of API changes:

- **Automatic Checking**: In development mode, the system automatically warns about unimplemented endpoints
- **Console Warnings**: Clear warnings appear in the browser console when new API endpoints are available
- **Implementation Stubs**: Provides ready-to-use code stubs for new endpoints
- **Schema Monitoring**: Detects when the OpenAPI schema changes

See `client/src/API_EVOLUTION.md` for detailed documentation on using this feature.