CORE PANEL

[ROOT] / home / csender / .trash / docs.2

EDIT :: API-Setup.md

# API Setup Guide

This guide explains how to configure and use the API client in the Legus Legal Case Management application.

## Overview

The API client is built with TypeScript and Axios, providing a robust, type-safe interface for backend communication. It includes automatic retry logic, comprehensive error handling, authentication management, and file upload capabilities. All configuration is managed through VITE_ prefixed environment variables.

## Configuration

### Environment Variables (.env)

Create a `.env` file in your project root with the following VITE_ prefixed variables:

```bash
# API Configuration - VITE_ prefix required for frontend access
VITE_API_BASE_URL=http://localhost:3000/api/v1
VITE_API_TIMEOUT=10000
VITE_API_RETRIES=3
VITE_API_RETRY_DELAY=1000
VITE_API_WITH_CREDENTIALS=false

# Application Configuration
VITE_APP_NAME=Legus - Legal Case Management
VITE_APP_VERSION=1.0.0

# Development Settings
VITE_DEBUG_MODE=true
VITE_MOCK_API=false

# Authentication Storage Keys
VITE_TOKEN_STORAGE_KEY=authToken
VITE_USER_STORAGE_KEY=currentUser
VITE_REFRESH_TOKEN_KEY=refreshToken
VITE_API_CACHE_KEY=apiCache

# Token Refresh Configuration (in milliseconds)
VITE_TOKEN_REFRESH_THRESHOLD=300000

# File Upload Configuration (size in bytes)
VITE_MAX_FILE_SIZE=10485760
VITE_ALLOWED_FILE_TYPES=.pdf,.doc,.docx,.txt,.jpg,.jpeg,.png,.gif

# API Retry Configuration  
VITE_API_BACKOFF_MULTIPLIER=2
VITE_API_MAX_RETRY_DELAY=10000

# Development API Settings
VITE_API_REQUEST_LOGGING=true
VITE_API_RESPONSE_LOGGING=true
```

### Environment Variable Details

| Variable | Default | Description |
|----------|---------|-------------|
| `VITE_API_BASE_URL` | `http://localhost:3000/api/v1` | Base URL for API endpoints |
| `VITE_API_TIMEOUT` | `10000` | Request timeout in milliseconds |
| `VITE_API_RETRIES` | `3` | Number of retry attempts for failed requests |
| `VITE_API_RETRY_DELAY` | `1000` | Base delay between retries in milliseconds |
| `VITE_API_WITH_CREDENTIALS` | `false` | Include cookies in requests |
| `VITE_DEBUG_MODE` | `false` | Enable debug logging |
| `VITE_API_REQUEST_LOGGING` | `false` | Log outgoing requests |
| `VITE_API_RESPONSE_LOGGING` | `false` | Log incoming responses |
| `VITE_TOKEN_STORAGE_KEY` | `authToken` | LocalStorage key for auth token |
| `VITE_USER_STORAGE_KEY` | `currentUser` | LocalStorage key for user data |
| `VITE_MAX_FILE_SIZE` | `10485760` | Maximum file upload size (10MB) |
| `VITE_API_BACKOFF_MULTIPLIER` | `2` | Exponential backoff multiplier |
| `VITE_API_MAX_RETRY_DELAY` | `10000` | Maximum retry delay in milliseconds |

### Configuration Files

The API configuration is managed through several files:

- `src/config/api.ts` - Centralized API configuration
- `src/utils/api.ts` - API client implementation
- `src/types/index.ts` - Type definitions
- `.env` - Environment variables (VITE_ prefixed)

## API Client Features

### 1. Environment-Based Configuration

All settings are controlled through VITE_ environment variables:

```typescript
// Automatically uses VITE_API_BASE_URL
const response = await apiClient.get('/users');

// Debug logging controlled by VITE_DEBUG_MODE
// Request/response logging by VITE_API_REQUEST_LOGGING & VITE_API_RESPONSE_LOGGING
```

### 2. Automatic Authentication

The API client automatically includes JWT tokens in requests:

```typescript
// Token is automatically added to Authorization header
const response = await apiClient.get('/users/profile');
```

### 3. Enhanced Error Handling

Comprehensive error handling with specific handlers for different scenarios:

```typescript
try {
  const data = await apiClient.get('/data');
} catch (error) {
  if (error instanceof ApiClientError) {
    console.log('Status:', error.status);
    console.log('Code:', error.code);
    console.log('Message:', error.message);
  }
}
```

### 4. Intelligent Retry Logic

Automatic retry for failed requests with exponential backoff:

- Network errors
- Server errors (5xx)
- Timeout errors
- Configurable retry count via `VITE_API_RETRIES`
- Exponential backoff via `VITE_API_BACKOFF_MULTIPLIER`
- Maximum delay cap via `VITE_API_MAX_RETRY_DELAY`

### 5. File Upload Support

Built-in file upload with progress tracking and configurable limits:

```typescript
const file = new File(['content'], 'document.pdf');

const response = await apiClient.uploadFile(
  '/documents/upload',
  file,
  (progress) => {
    console.log(`Upload progress: ${progress.loaded}/${progress.total}`);
  }
);
```

## Usage Examples

### Environment Configuration Validation

```typescript
import { validateEnvironmentVariables } from '@/config/api';

// Check if all required environment variables are set
const validation = validateEnvironmentVariables();
if (!validation.valid) {
  console.error('Missing environment variables:', validation.missing);
}
```

### Basic API Calls

```typescript
import { apiClient } from '@/api';

// GET request (uses VITE_API_BASE_URL + VITE_API_TIMEOUT)
const users = await apiClient.get<User[]>('/users');

// POST request
const newUser = await apiClient.post<User>('/users', {
  name: 'John Doe',
  email: 'john@example.com'
});

// PUT request
const updatedUser = await apiClient.put<User>(`/users/${id}`, userData);

// DELETE request
await apiClient.delete(`/users/${id}`);
```

### Using API Services

```typescript
import { usersApi, casesApi, clientsApi } from '@/api';

// Get all users
const users = await usersApi.getUsers(1, 10);

// Create a new case
const newCase = await casesApi.createCase({
  title: 'Personal Injury Case',
  clientId: 'client-123',
  // ... other case data
});

// Search clients
const clients = await clientsApi.searchClients('office-1', 'john');
```

### Authentication

```typescript
import { usersApi, apiClient } from '@/api';

// Login
const loginResponse = await usersApi.login({
  username: 'admin@example.com',
  password: 'password123'
});

// The token is automatically stored using VITE_TOKEN_STORAGE_KEY

// Get current user profile
const profile = await usersApi.getCurrentProfile();

// Logout
await usersApi.logout();
```

### Advanced Configuration Access

```typescript
import { 
  getApiConfig, 
  debugConfig, 
  authConfig, 
  uploadConfig,
  appConfig 
} from '@/config/api';

// Get current API configuration
const config = getApiConfig();
console.log('API Base URL:', config.baseURL);

// Check debug settings
if (debugConfig.enabled) {
  console.log('Debug mode is enabled');
}

// Access upload limits
console.log('Max file size:', uploadConfig.maxFileSize);
console.log('Allowed types:', uploadConfig.allowedTypes);

// App information
console.log('App:', appConfig.name, 'v' + appConfig.version);
```

## Health Checks and Monitoring

### Enhanced Initialization

```typescript
// Initialize with comprehensive validation
const initResult = await apiClient.initialize();

console.log('Initialization success:', initResult.success);
console.log('Environment validation:', initResult.envValidation);
console.log('Connected to API:', initResult.connected);

if (!initResult.success) {
  console.error('Errors:', initResult.errors);
  console.warn('Warnings:', initResult.warnings);
}
```

### Connection Testing

```typescript
// Simple health check
const isHealthy = await apiClient.healthCheck();

// Detailed connection test
const status = await apiClient.testConnection();
console.log(`Connected: ${status.connected}, Latency: ${status.latency}ms`);

// Get comprehensive API status
const apiStatus = await apiClient.getApiStatus();
```

## Development vs Production

### Development Configuration

```bash
VITE_DEBUG_MODE=true
VITE_API_REQUEST_LOGGING=true
VITE_API_RESPONSE_LOGGING=true
VITE_API_BASE_URL=http://localhost:3000/api/v1
```

### Production Configuration

```bash
VITE_DEBUG_MODE=false
VITE_API_REQUEST_LOGGING=false
VITE_API_RESPONSE_LOGGING=false
VITE_API_BASE_URL=https://api.yourdomain.com/v1
VITE_API_WITH_CREDENTIALS=true
```

## Troubleshooting

### Environment Variable Issues

1. **Variables not loading**: Ensure they have `VITE_` prefix
2. **Build-time vs Runtime**: VITE_ variables are injected at build time
3. **Boolean values**: Use string `'true'` or `'false'`

### Debug Information

Enable debug mode to get detailed logging:

```bash
VITE_DEBUG_MODE=true
VITE_API_REQUEST_LOGGING=true
VITE_API_RESPONSE_LOGGING=true
```

This enables:
- 🔄 Request logging with headers and data
- ✅ Response logging with status and data
- ❌ Error logging with full details
- 🔄 Retry attempt logging with delays
- 🚀 Initialization logging
- 🔧 Configuration display

### Testing Environment Setup

Use the API Example component to verify your environment configuration:

1. Check if variables are loaded correctly
2. Test API connection
3. Verify retry logic
4. Test error handling

## Security Considerations

### Environment Variables

- Never commit `.env` files to version control
- Use different `.env` files for different environments
- Validate all environment variables on startup
- Use strong, unique storage keys in production

### Production Checklist

- [ ] `VITE_DEBUG_MODE=false`
- [ ] `VITE_API_BASE_URL` points to production API
- [ ] `VITE_API_WITH_CREDENTIALS=true` if using cookies
- [ ] Strong, unique `VITE_TOKEN_STORAGE_KEY`
- [ ] Appropriate timeout values
- [ ] HTTPS URLs only

This comprehensive environment-based configuration system provides maximum flexibility while maintaining security and ease of deployment across different environments.

CANCEL

// SYSTEM PANEL //

EDIT :: API-Setup.md