veza/docs/archive/frontend-sessions-2026/MIGRATION_GUIDE.md

# Guide de Migration : ApiService → apiClient

## Vue d'ensemble

`ApiService` est déprécié en faveur de `apiClient` pour unifier les clients API et éviter la duplication de code.

## Pourquoi migrer ?

- **Unification** : Un seul client API au lieu de deux
- **Maintenance** : Moins de code à maintenir
- **Cohérence** : Même comportement partout (gestion d'erreurs, refresh token, etc.)
- **Performance** : Pas de duplication d'instances Axios

## Comment migrer

### Import

**Avant :**
```typescript
import { apiService } from '@/services/api';
```

**Après :**
```typescript
import { apiClient } from '@/services/api/client';
```

### Méthodes d'authentification

**Avant :**
```typescript
const { user, tokens } = await apiService.login(credentials);
const user = await apiService.getCurrentUser();
await apiService.logout();
```

**Après :**
```typescript
import { authApi } from '@/features/auth/api/authApi';

const response = await authApi.login(credentials);
const user = await authApi.getMe();
await authApi.logout(refreshToken);
```

### Méthodes utilisateurs

**Avant :**
```typescript
const users = await apiService.getUsers({ page: 1, limit: 20 });
const user = await apiService.getUser(id);
const user = await apiService.getUserByUsername(username);
await apiService.updateUser(id, data);
```

**Après :**
```typescript
const { data: users } = await apiClient.get('/users', { params: { page: 1, limit: 20 } });
const { data: user } = await apiClient.get(`/users/${id}`);
const { data: user } = await apiClient.get(`/users/by-username/${username}`);
await apiClient.put(`/users/${id}`, data);
```

### Méthodes tracks

**Avant :**
```typescript
const tracks = await apiService.getTracks({ page: 1, limit: 20 });
const track = await apiService.getTrack(id);
await apiService.uploadTrack(file, metadata);
await apiService.deleteTrack(id);
```

**Après :**
```typescript
import { trackApi } from '@/features/tracks/api/trackApi';

const { data: tracks } = await apiClient.get('/tracks', { params: { page: 1, limit: 20 } });
const { data: track } = await apiClient.get(`/tracks/${id}`);
await trackApi.uploadTrack(file, metadata);
await apiClient.delete(`/tracks/${id}`);
```

### Méthodes conversations

**Avant :**
```typescript
const conversations = await apiService.getConversations();
const conversation = await apiService.getConversation(id);
await apiService.addMemberToConversation(id, userId);
const { messages } = await apiService.getConversationHistory(id, { limit: 50 });
```

**Après :**
```typescript
const { data: conversations } = await apiClient.get('/conversations');
const { data: conversation } = await apiClient.get(`/conversations/${id}`);
await apiClient.post(`/conversations/${id}/members`, { user_id: userId });
const { data } = await apiClient.get(`/conversations/${id}/history`, { params: { limit: 50 } });
const messages = data.messages || [];
```

### Méthodes messages

**Avant :**
```typescript
const messages = await apiService.getMessages(conversationId, { page: 1, limit: 50 });
await apiService.sendMessage(conversationId, content, parentMessageId);
```

**Après :**
```typescript
const { data: messages } = await apiClient.get('/messages', {
  params: { conversation_id: conversationId, page: 1, limit: 50 }
});
await apiClient.post('/messages', {
  conversation_id: conversationId,
  content,
  parent_message_id: parentMessageId
});
```

### Méthodes sessions

**Avant :**
```typescript
await apiService.logoutSession();
await apiService.logoutAllSessions();
const sessions = await apiService.getSessions();
await apiService.revokeSession(sessionId);
const stats = await apiService.getSessionStats();
await apiService.refreshSession();
```

**Après :**
```typescript
await apiClient.post('/sessions/logout');
await apiClient.post('/sessions/logout-all');
const { data: sessions } = await apiClient.get('/sessions');
await apiClient.delete(`/sessions/${sessionId}`);
const { data: stats } = await apiClient.get('/sessions/stats');
await apiClient.post('/sessions/refresh');
```

## Notes importantes

1. **Format de réponse** : `apiClient` unwrap automatiquement le format `{ success: true, data: {...} }` du backend, donc `response.data` contient directement les données.

2. **Gestion d'erreurs** : `apiClient` utilise `parseApiError` pour standardiser les erreurs. Les erreurs sont automatiquement parsées en `ApiError`.

3. **Refresh token** : `apiClient` gère automatiquement le refresh du token en cas de 401, pas besoin de le faire manuellement.

4. **Types** : Utilisez les types TypeScript appropriés pour les réponses :
   ```typescript
   const { data: user } = await apiClient.get<User>('/users/123');
   ```

## Fichiers à migrer

- `apps/web/src/stores/library.ts`
- `apps/web/src/features/library/components/LibraryManager.tsx`
- `apps/web/src/features/user/components/ProfileForm.tsx`
- `apps/web/src/stores/chat.ts`
- `apps/web/src/features/chat/components/VirtualizedChatMessages.tsx`
- `apps/web/src/features/chat/components/ChatInterface.tsx`
- `apps/web/src/features/library/components/UploadModal.tsx`

## Timeline

- **Phase 1** (Maintenant) : `ApiService` est marqué comme deprecated avec warnings
- **Phase 2** (Prochaine release) : Migration progressive des fichiers listés ci-dessus
- **Phase 3** (Version future) : Suppression complète de `ApiService`