ai-voicebot/docs/API_EVOLUTION.md

# API Evolution Detection System

This system automatically detects when your OpenAPI schema has new endpoints or changed parameters that need to be implemented in the `ApiClient` class.

## How It Works

### Automatic Detection
- **Development Mode**: Automatically runs when `api-client.ts` is imported during development
- **Runtime Checking**: Compares available endpoints in the OpenAPI schema with implemented methods
- **Console Warnings**: Displays detailed warnings about unimplemented endpoints

### Schema Comparison
- **Hash-based Detection**: Detects when the OpenAPI schema file changes
- **Endpoint Analysis**: Identifies new, changed, or unimplemented endpoints
- **Parameter Validation**: Suggests checking for parameter changes

## Usage

### Automatic Checking
The system runs automatically in development mode when you import from `api-client.ts`:

```typescript
import { apiClient } from './api-client';
// Check runs automatically after 1 second delay
```

### Command Line Checking
You can run API evolution checks from the command line:

```bash
# Full type generation with evolution check
./generate-ts-types.sh

# Quick evolution check only (without regenerating types)
./check-api-evolution.sh

# Or from within the client container
npm run check-api-evolution
```

### Manual Checking
You can manually trigger checks during development:

```typescript
import { devUtils } from './api-client';

// Check for API evolution
const evolution = await devUtils.checkApiEvolution();

// Force recheck (bypasses once-per-session limit)
devUtils.recheckEndpoints();
```

### Console Output
When unimplemented endpoints are found, you'll see:

**Browser Console (development mode):**
```
🚨 API Evolution Detection
🆕 New API endpoints detected:
  • GET /ai-voicebot/api/new-feature (get_new_feature_endpoint)
⚠️  Unimplemented API endpoints:
  • POST /ai-voicebot/api/admin/bulk-action
💡 Implementation suggestions:
Add these methods to ApiClient:
  async adminBulkAction(): Promise<any> {
    return this.request<any>('/ai-voicebot/api/admin/bulk-action', { method: 'POST' });
  }
```

**Command Line:**
```
🔍 API Evolution Check
==================================================
📊 Summary:
   Total endpoints: 8
   Implemented: 7
   Unimplemented: 1

⚠️  Unimplemented API endpoints:
   • POST /ai-voicebot/api/admin/bulk-action
     Admin bulk action endpoint

💡 Implementation suggestions:
Add these methods to the ApiClient class:

  async adminBulkAction(data?: any): Promise<any> {
    return this.request<any>('/ai-voicebot/api/admin/bulk-action', { method: 'POST', body: data });
  }
```

## Configuration

### Implemented Endpoints Registry
The system maintains a registry of implemented endpoints in `ApiClient`. When you add new methods, update the registry:

```typescript
// In api-evolution-checker.ts
private getImplementedEndpoints(): Set<string> {
  return new Set([
    'GET:/ai-voicebot/api/admin/names',
    'POST:/ai-voicebot/api/admin/set_password',
    // Add new endpoints here:
    'POST:/ai-voicebot/api/admin/bulk-action',
  ]);
}
```

### Schema Location
The system attempts to load the OpenAPI schema from:
- `/openapi-schema.json` (served by your development server)
- Falls back to hardcoded endpoint list if schema file is unavailable

## Development Workflow

### When Adding New API Endpoints

1. **Add endpoint to FastAPI server** (server/main.py)
2. **Regenerate types**: Run `./generate-ts-types.sh`
3. **Check console** for warnings about unimplemented endpoints
4. **Implement methods** in `ApiClient` class
5. **Update endpoint registry** in the evolution checker
6. **Add convenience methods** to API namespaces if needed

### Example Implementation

When you see a warning like:
```
⚠️  Unimplemented: POST /ai-voicebot/api/admin/bulk-action
```

1. Add the method to `ApiClient`:
```typescript
async adminBulkAction(data: BulkActionRequest): Promise<BulkActionResponse> {
  return this.request<BulkActionResponse>('/ai-voicebot/api/admin/bulk-action', { 
    method: 'POST', 
    body: data 
  });
}
```

2. Add to convenience API:
```typescript
export const adminApi = {
  listNames: () => apiClient.adminListNames(),
  setPassword: (data: AdminSetPassword) => apiClient.adminSetPassword(data),
  clearPassword: (data: AdminClearPassword) => apiClient.adminClearPassword(data),
  bulkAction: (data: BulkActionRequest) => apiClient.adminBulkAction(data), // New
};
```

3. Update the registry:
```typescript
private getImplementedEndpoints(): Set<string> {
  return new Set([
    // ... existing endpoints ...
    'POST:/ai-voicebot/api/admin/bulk-action', // Add this
  ]);
}
```

## Benefits

- **Prevents Missing Implementations**: Never forget to implement new API endpoints
- **Development Efficiency**: Automatic detection saves time during API evolution
- **Type Safety**: Works with generated TypeScript types for full type safety
- **Code Generation**: Provides implementation stubs to get started quickly
- **Schema Validation**: Detects when OpenAPI schema changes

## Production Considerations

- **Development Only**: Evolution checking only runs in development mode
- **Performance**: Minimal runtime overhead (single check per session)
- **Error Handling**: Gracefully falls back if schema loading fails
- **Console Logging**: All output goes to console.warn/info for easy filtering