Référence API

Référence rapide pour le SDK JavaScript Optave. Pour des exemples détaillés, voir Exemples d'Utilisation.

Constructeur

new OptaveJavaScriptSDK(options)

Crée une nouvelle instance du SDK.

Options Principales:

• websocketUrl (string, requis): URL du serveur WebSocket
• tokenProvider (function, navigateur): Fonction asynchrone retournant un token WebSocket
• authenticationUrl (string, serveur): Endpoint d'authentification OAuth2
• clientId (string, serveur): ID client OAuth2
• clientSecret (string, serveur): Secret client OAuth2 (serveur uniquement!)
• authTransport (string): 'subprotocol' (par défaut) ou 'query'
• connectionTimeoutMs (number): Timeout de connexion (par défaut: 30000ms)
• requestTimeoutMs (number): Timeout de requête (par défaut: 30000ms)
• strictValidation (boolean): Activer la validation du payload (par défaut: true en dev)
• logger (object): Logger personnalisé avec méthodes debug/info/warn/error

Exemple:

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 res = await fetch('/api/optave-token', { method: 'POST' });
    const { token } = await res.json();
    return token;
  }
});

Méthodes de Connexion

authenticate()

Authentifie en utilisant les identifiants client OAuth2 (serveur uniquement).

• Retourne: Promise<string> - Token d'accès
• Note: Non disponible dans les builds navigateur

openConnection(bearerToken?)

Établit la connexion WebSocket.

• Paramètres: bearerToken (string, optionnel) - Token pré-obtenu
• Retourne: Promise<Event> - Se résout quand connecté

closeConnection()

Ferme la connexion WebSocket.

cleanup()

Nettoyage complet de toutes les ressources (connexion, listeners, requêtes en attente).

Méthodes d'Action (Basées sur Événements)

Envoyer des messages sans attendre de réponses. Écouter les réponses via événements.

• interaction(params): Envoyer une interaction client
• reception(params): Envoyer un message de réception
• elevate(params): Demander une élévation de réponse
• adjust(params): Demander un ajustement de réponse
• summarize(params): Demander un résumé de conversation
• translate(params): Demander une traduction
• recommend(params): Demander des recommandations
• insights(params): Demander des insights analytiques

Événements

Événements de Connexion

• 'open': Connexion établie
• 'close': Connexion fermée
• 'error': Erreur de connexion (obsolète, utiliser 'superpower.error')

Événements de Message

• 'superpower.response': Réponse reçue (recommandé)
• 'superpower.error': Erreur survenue (recommandé)
• 'message': Événement de réponse hérité (obsolète)
• 'response': Événement de réponse alternatif
• 'message.{action}': Événements spécifiques à l'action (ex: 'message.summarize')

Exemple:

client.on('superpower.response', (response) => {
  console.log('Reçu:', response.payload);
});

client.on('superpower.error', (error) => {
  console.error('Erreur:', error.message);
});

Structure d'Erreur

Toutes les erreurs utilisent un format structuré:

{
  category: 'AUTHENTICATION' | 'VALIDATION' | 'WEBSOCKET' | 'ORCHESTRATOR',
  code: string,
  message: string,
  details: any,
  correlationId?: string,
  timestamp: string
}

Codes d'Erreur Courants:

• CONNECTION_TIMEOUT: La connexion a pris trop de temps
• REQUEST_TIMEOUT: La requête a expiré
• REQUIRED_FIELDS_MISSING: Champs requis manquants dans le payload
• PAYLOAD_TOO_LARGE: Le payload dépasse la limite de 128KB
• WEBSOCKET_NOT_IN_OPEN_STATE: Non connecté