Gestion des Événements

Le SDK émet plusieurs événements pour gérer divers états et messages. Vous pouvez écouter ces événements pour gérer le comportement de votre application en conséquence.

Événements Disponibles

Événements de Connexion

• open: Émis lorsque la connexion WebSocket est ouverte avec succès.
• close: Émis lorsque la connexion WebSocket est fermée.

Événements de Message

• message: Émis lorsqu'un message est reçu du serveur.
• superpower.response: Événement moderne pour gérer les réponses du serveur (recommandé).
• message.{action}: Événements spécifiques à l'action (ex: message.summarize, message.translate).

Événements d'Erreur

• error: Émis lorsqu'une erreur se produit.
• superpower.error: Événement moderne pour les erreurs structurées (recommandé).

Écoute d'Événements de Base

client.on('open', () => {
    console.log('Connexion WebSocket ouverte.');
});

client.on('message', (payload) => {
    console.log('Message reçu:', payload);
});

client.on('error', (error) => {
    console.error('Une erreur est survenue:', error);
});

client.on('close', (event) => {
    console.log('Connexion WebSocket fermée:', event.code);
});

Noms d'Événements Modernes

Pour le nouveau code, utilisez les noms d'événements modernes:

// Recommandé: Noms d'événements modernes
client.on('superpower.response', (response) => {
    console.log('Réponse reçue:', response);

    if (response.status === 'success') {
        console.log('Action réussie:', response.action);
        console.log('Données de réponse:', response.data);
    }
});

client.on('superpower.error', (error) => {
    console.error(`[${error.category}] ${error.code}:`, error.message);
});

Événements Spécifiques à l'Action

Écoutez des opérations IA spécifiques sans filtrage manuel:

// Écouter uniquement les réponses de résumé
client.on('message.summarize', (response) => {
      const results = response.payload.message.results;
      if (results && results.length > 0) {
          const content = results[0].response[0].content;
          console.log('Résumé reçu:', content);
          displaySummary(content);
      }
  });

client.on('message.translate', (response) => {
    const results = response.payload.message.results;
    if (results && results.length > 0) {
        const content = results[0].response[0].content;
        console.log('Traduction reçue:', content);
        displayTranslation(content);
    }
});

client.on('message.recommend', (response) => {
    const results = response.payload.message.results;
    if (results && results.length > 0) {
        // Les recommandations peuvent contenir plusieurs éléments
        const recommendations = results[0].response;
        console.log('Recommandations:', recommendations);
        displayRecommendations(recommendations);
    }
});

Événements d'action disponibles:

• message.adjust
• message.elevate
• message.interaction
• message.reception
• message.summarize
• message.translate
• message.recommend
• message.insights

Gestion des Erreurs

Le SDK inclut une gestion d'erreurs structurée avec catégorisation et suggestions de dépannage.

Catégories d'Erreur

• AUTHENTICATION: Erreurs d'authentification et d'autorisation
• WEBSOCKET: Erreurs de connexion et de transport
• VALIDATION: Erreurs de validation de payload et de schéma
• ORCHESTRATOR: Erreurs d'orchestration côté serveur

Structure d'Objet d'Erreur

{
    category: 'WEBSOCKET', // Catégorie d'erreur
    code: 'INVALID_WEBSOCKET_URL', // Code d'erreur
    message: 'Empty or invalid Websocket URL', // Message d'erreur
    details: null, // Contexte d'erreur supplémentaire
    suggestions: [], // Suggestions de dépannage
    correlationId: 'abc123', // ID de corrélation de requête (le cas échéant)
    timestamp: '2025-01-15T10:30:00.000Z' // Horodatage ISO 8601
}

Gérer les Erreurs

client.on('error', (error) => {
    console.error(`[${error.category}] ${error.code}: ${error.message}`);

    // Afficher les suggestions si disponibles
    if (error.suggestions && error.suggestions.length > 0) {
        console.log('Suggestions:');
        error.suggestions.forEach(suggestion => {
            console.log(`  - ${suggestion}`);
        });
    }

    // Gestion spécifique à la catégorie
    switch (error.category) {
        case 'AUTHENTICATION':
            handleAuthError(error);
            break;
        case 'WEBSOCKET':
            handleConnectionError(error);
            break;
        case 'VALIDATION':
            handleValidationError(error);
            break;
    }
});

Gestion des Événements

Écouteurs Une Seule Fois

Écouter un événement une seule fois:

client.once('open', () => {
    console.log('Première connexion établie');
});

Supprimer les Écouteurs

// Définir une fonction nommée pour la suppression
function handleMessage(message) {
    console.log('Message:', message);
}

// Ajouter un écouteur
client.on('message', handleMessage);

// Supprimer un écouteur spécifique
client.off('message', handleMessage);

// Supprimer tous les écouteurs pour un événement
client.removeAllListeners('message');

Modèle de Nettoyage

Supprimez toujours les écouteurs lorsque les composants se démontent pour éviter les fuites de mémoire:

// Exemple React
useEffect(() => {
    const handleMessage = (message) => console.log(message);
    const handleError = (error) => console.error(error);

    client.on('message', handleMessage);
    client.on('error', handleError);

    // Nettoyage au démontage
    return () => {
        client.off('message', handleMessage);
        client.off('error', handleError);
    };
}, [client]);

Exemple Complet

import OptaveJavaScriptSDK from '@optave/client-sdk';

const client = new OptaveJavaScriptSDK({
    websocketUrl: 'wss://ws-{{tenant}}.oco.optave.{{tld}}',
    authTransport: 'subprotocol',
    tokenProvider: async () => {
        // Remplacez '/api/optave-token' par votre véritable endpoint backend
        const response = await fetch('/api/optave-token');
        return (await response.json()).token;
    }
});

// Événements de connexion
client.on('open', () => {
    console.log('✓ Connecté');
    updateStatus('connected');
});

client.on('close', (event) => {
    console.log(`✗ Déconnecté: ${event.code}`);
    updateStatus('disconnected');

    if (!event.wasClean) {
        setTimeout(() => reconnect(), 5000);
    }
});

// Gestion des messages
client.on('superpower.response', (response) => {
    console.log(`Réponse pour ${response.action}:`, response);

    if (response.status === 'success') {
        displayResponse(response);
    }
});

// Gestionnaires spécifiques à l'action
client.on('message.summarize', (response) => {
      const results = response.payload.message.results;
      if (results && results.length > 0) {
          const content = results[0].response[0].content;
          console.log('Résumé reçu:', content);
          displaySummary(content);
      }
});

// Gestion des erreurs
client.on('superpower.error', (error) => {
    console.error(`[${error.category}] ${error.code}:`, error.message);

    switch (error.category) {
        case 'AUTHENTICATION':
            handleAuthenticationError(error);
            break;
        case 'WEBSOCKET':
            handleConnectionError(error);
            break;
        case 'VALIDATION':
            handleValidationError(error);
            break;
    }
});

// Connecter
await client.openConnection();