Version: 3.2.1

Installation & Configuration

Installation

Le SDK Client Optave est distribué via npm et prend en charge plusieurs méthodes d'installation. Le package fournit des builds optimisés pour différents environnements (navigateur et Node.js) avec sélection automatique du build.

Installation Rapide

Installer via npm (recommandé):

npm install @optave/client-sdk

Ou en utilisant Yarn:

yarn add @optave/client-sdk

Prérequis

Node.js: 20.0.0 ou supérieur (pour utilisation côté serveur)
Navigateurs Modernes: Chrome 80+, Firefox 74+, Safari 14.1+, Edge 80+
Gestionnaire de Paquets: npm 10.8.1+ ou Yarn 1.22+

Dépendances de Performance Optionnelles

Pour des performances WebSocket améliorées dans les environnements serveur Node.js, installez ces dépendances natives optionnelles:

npm install --save-optional bufferutil utf-8-validate

Avantages:

bufferutil: Jusqu'à 2x plus rapide pour le masquage et démasquage des trames WebSocket utilisant des implémentations C++ natives
utf-8-validate: Validation UTF-8 efficace pour les messages WebSocket (conformité RFC)
Utilisation CPU réduite pour les applications à haut débit
Repli automatique vers les implémentations JavaScript si non disponibles

Note: Celles-ci sont uniquement bénéfiques dans Node.js environnements serveur. Les applications navigateur n'en ont pas besoin et le SDK fonctionne parfaitement sans elles.

Système de Build & Imports

Le SDK fournit quatre builds optimisés pour différents scénarios de déploiement. Le package sélectionne automatiquement le build approprié selon votre environnement.

Builds Disponibles

Build	Format Module	Secrets Client	Validation AJV	CSP Safe	Taille (Gzippé)	Cas d'Usage
Browser ESM	ES Module	❌ Non	Externe Seulement	✅ Oui	~14KB	Bundlers modernes (Vite, Webpack 5+), React, Vue
Browser UMD	UMD	❌ Non	Externe Seulement	✅ Oui	~15KB	Salesforce Lightning, CDN, navigateurs anciens
Server ESM	ES Module	✅ Oui	Complet (intégré)	❌ Non	~25KB	Serveurs Node.js, Express, Fastify, microservices
Server UMD	UMD	✅ Oui	Externe Seulement	✅ Oui	~14KB	Node.js CommonJS, environnements mixtes

Sélection Automatique du Build (Recommandé)

Le SDK sélectionne automatiquement le bon build selon votre environnement:

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

// Se résout automatiquement en:
// - browser.mjs dans les environnements navigateur (Vite, Webpack, bundlers)
// - server.mjs dans les environnements Node.js

Cette méthode est recommandée car elle assure une sélection optimale du build sans configuration manuelle.

Sélection Explicite du Build

Pour les cas d'usage avancés nécessitant des builds spécifiques:

Environnements Navigateur:

// ES Module (recommandé pour les bundlers modernes)
import OptaveJavaScriptSDK from '@optave/client-sdk/browser';

// UMD (pour navigateurs anciens, Salesforce Lightning, ou utilisation CDN)
import OptaveJavaScriptSDK from '@optave/client-sdk/browser-umd';

Environnements Node.js:

// ES Module (recommandé pour Node.js moderne avec "type": "module")
import OptaveJavaScriptSDK from '@optave/client-sdk/server';

// UMD (compatible CommonJS - fonctionne avec require())
const OptaveJavaScriptSDK = require('@optave/client-sdk/server-umd');

Utilisation CDN (Navigateur Uniquement)

ES Module depuis CDN (unpkg):

<script type="module">
  import OptaveJavaScriptSDK from 'https://app.unpkg.com/@optave/client-sdk@3.2.4/files/dist/browser.mjs';

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

UMD depuis CDN (variable globale):

<script src="https://app.unpkg.com/@optave/client-sdk@3.2.4/files/dist/browser.umd.js"></script>
<script>
  // OptaveJavaScriptSDK est maintenant disponible globalement
  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');
      const { token } = await response.json();
      return token;
    }
  });
</script>

Exemples Spécifiques aux Frameworks

React (Create React App, Vite, Next.js):

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

function App() {
  const [client] = useState(() => 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 response.json().then(data => data.token);
    }
  }));

  // Utiliser le client...
}

Vue 3 (Vite):

import { ref, onMounted } from 'vue';
import OptaveJavaScriptSDK from '@optave/client-sdk';

export default {
  setup() {
    const client = ref(null);

    onMounted(() => {
      client.value = 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');
          const data = await response.json();
          return data.token;
        }
      });
    });

    return { client };
  }
};

Node.js (Express, Fastify):

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

const app = express();

// Initialiser le SDK avec les identifiants client
const client = new OptaveJavaScriptSDK({
  websocketUrl: process.env.OPTAVE_WEBSOCKET_URL,
  authenticationUrl: process.env.OPTAVE_AUTHENTICATION_URL,
  clientId: process.env.OPTAVE_CLIENT_ID,
  clientSecret: process.env.OPTAVE_CLIENT_SECRET
});

app.listen(3000);

TypeScript (Support de Type Complet):

import OptaveJavaScriptSDK from '@optave/client-sdk';
import type { SDKConfiguration } from '@optave/client-sdk';

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

const client = new OptaveJavaScriptSDK(config);

Composant Lightning Salesforce:

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

export default class OptaveIntegration extends LightningElement {
  connectedCallback() {
    this.client = new OptaveJavaScriptSDK({
      websocketUrl: 'wss://ws-{{tenant}}.oco.optave.{{tld}}',
      authTransport: 'subprotocol',
      tokenProvider: async () => {
        // Utiliser Salesforce Apex pour récupérer le token
        return getOptaveToken();
      }
    });
  }
}

Configuration

Le SDK nécessite des paramètres de configuration spécifiques selon votre méthode d'authentification et environnement de déploiement.

Options de Configuration

Paramètre	Type	Requis	Environnement	Description
`websocketUrl`	`string`	✅ Oui	Tous	URL du endpoint WebSocket (ex: `wss://ws-{{tenant}}.oco.optave.{{tld}}`)
`tokenProvider`	`async function`	Navigateur	Navigateur	Fonction asynchrone qui retourne un token d'authentification valide
`authenticationUrl`	`string`	Serveur*	Serveur	URL du endpoint API d'authentification
`clientId`	`string`	Serveur*	Serveur	ID client pour le flux OAuth2 client credentials
`clientSecret`	`string`	Serveur*	Serveur	Secret client pour le flux OAuth2 client credentials
`authTransport`	`string`	Non	Tous	Comment envoyer le token: `'subprotocol'` (par défaut, recommandé) ou `'query'`
`connectionTimeoutMs`	`number`	Non	Tous	Timeout de connexion en millisecondes (par défaut: 30000)
`requestTimeoutMs`	`number`	Non	Tous	Timeout de requête en millisecondes (par défaut: 30000)
`strictValidation`	`boolean`	Non	Tous	Activer la validation du payload (par défaut: true en dev, false en production)

*Note: Pour les environnements serveur, soit tokenProvider OU (authenticationUrl + clientId + clientSecret) est requis.

Exemples de Configuration

Configuration Navigateur (Pattern Token Provider)

Approche recommandée pour les applications navigateur/frontend:

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

const client = new OptaveJavaScriptSDK({
  websocketUrl: 'wss://ws-{{tenant}}.oco.optave.{{tld}}',
  authTransport: 'subprotocol', // Comment envoyer le token d'authentification (par défaut: 'subprotocol', ou 'query')

  // Fonction token provider - appelée automatiquement quand le SDK a besoin d'authentification
  tokenProvider: async () => {
    // Récupérer le token depuis votre backend sécurisé
    // Remplacez '/api/optave-token' par votre véritable endpoint backend
    const response = await fetch('/api/optave-token', {
      method: 'POST',
      credentials: 'include', // Inclure les cookies pour la validation de session
      headers: {
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error('Échec de la récupération du token Optave');
    }

    const data = await response.json();
    return data.token; // Retourner la chaîne du token
  }
});

Pourquoi utiliser tokenProvider dans les navigateurs?

✅ N'expose jamais les secrets client dans le code frontend
✅ Le backend contrôle l'authentification et l'émission des tokens
✅ Suit les meilleures pratiques OAuth2 pour les clients publics
✅ Prend en charge l'authentification basée sur session

Configuration Serveur (Client Credentials)

Approche recommandée pour les applications backend/serveur:

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

const client = new OptaveJavaScriptSDK({
  websocketUrl: process.env.OPTAVE_WEBSOCKET_URL,
  authenticationUrl: process.env.OPTAVE_AUTHENTICATION_URL,
  clientId: process.env.OPTAVE_CLIENT_ID,
  clientSecret: process.env.OPTAVE_CLIENT_SECRET
});

Variables d'Environnement (fichier .env):

OPTAVE_WEBSOCKET_URL=wss://ws-{{tenant}}.oco.optave.{{tld}}
OPTAVE_AUTHENTICATION_URL=https://auth.optave.tech/oauth/token
OPTAVE_CLIENT_ID=your_client_id_here
OPTAVE_CLIENT_SECRET=your_client_secret_here

Pourquoi utiliser les identifiants client sur les serveurs?

✅ Authentification serveur à serveur sécurisée
✅ Flux complet OAuth2 client credentials
✅ Rafraîchissement et gestion automatique des tokens
✅ Adapté aux APIs backend, microservices et tâches serveur

Configuration Serveur (Alternative Token Provider)

Les serveurs peuvent également utiliser tokenProvider pour des flux d'authentification personnalisés:

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

const client = new OptaveJavaScriptSDK({
  websocketUrl: process.env.OPTAVE_WEBSOCKET_URL,

  tokenProvider: async () => {
    // Logique d'acquisition de token personnalisée
    // Exemple: Récupérer depuis un fournisseur d'identité externe, cache, ou coffre-fort
    const token = await yourCustomTokenService.getToken();
    return token;
  }
});

Exemple de Configuration Complète (Serveur)

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

// Charger les variables d'environnement
dotenv.config();

const client = new OptaveJavaScriptSDK({
  // Requis: URL de connexion WebSocket
  websocketUrl: process.env.OPTAVE_WEBSOCKET_URL,

  // Requis pour le flux client credentials
  authenticationUrl: process.env.OPTAVE_AUTHENTICATION_URL,
  clientId: process.env.OPTAVE_CLIENT_ID,
  clientSecret: process.env.OPTAVE_CLIENT_SECRET,

  // Optionnel: Configuration personnalisée
  timeout: 30000, // Timeout de connexion en millisecondes (par défaut: 30000)
  maxReconnectAttempts: 5, // Tentatives de reconnexion max (par défaut: Infinity)
  reconnectDelay: 1000 // Délai entre les tentatives de reconnexion en ms (par défaut: 1000)
});

// Gestionnaires d'événements
client.on('connected', () => {
  console.log('Connecté au WebSocket Optave');
});

client.on('authenticated', () => {
  console.log('Authentification réussie');
});

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

// Établir la connexion
await client.connect();

Meilleures Pratiques de Sécurité

Applications Navigateur

Ne jamais exposer les secrets client dans le code frontend ou les variables d'environnement accessibles au navigateur
Toujours utiliser le pattern tokenProvider pour récupérer les tokens depuis votre backend sécurisé
Valider les sessions utilisateur sur votre backend avant d'émettre des tokens Optave
Implémenter une limitation de débit sur votre endpoint de token pour éviter les abus
Utiliser HTTPS pour toutes les requêtes de récupération de token
Définir des politiques CORS appropriées sur votre endpoint de token

Exemple d'Endpoint Backend Sécurisé pour Token (Node.js/Express):

// Ceci est un endpoint d'exemple - remplacez '/api/optave-token' par votre route préférée
app.post('/api/optave-token', authenticateUser, async (req, res) => {
  // Vérifier que l'utilisateur est authentifié
  if (!req.user) {
    return res.status(401).json({ error: 'Non autorisé' });
  }

  try {
    // Utiliser le SDK serveur pour obtenir un token via client credentials
    const response = await fetch(process.env.OPTAVE_AUTHENTICATION_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        grant_type: 'client_credentials',
        client_id: process.env.OPTAVE_CLIENT_ID,
        client_secret: process.env.OPTAVE_CLIENT_SECRET
      })
    });

    const data = await response.json();

    // Retourner le token au frontend authentifié
    res.json({ token: data.access_token });
  } catch (error) {
    res.status(500).json({ error: 'Échec de l\'obtention du token' });
  }
});

Applications Serveur

Stocker les identifiants en toute sécurité en utilisant des variables d'environnement ou des systèmes de gestion de secrets (AWS Secrets Manager, HashiCorp Vault, etc.)
Ne jamais commiter les secrets dans le contrôle de version (utiliser .gitignore pour les fichiers .env)
Rotation régulière des identifiants dans le cadre de la maintenance de sécurité
Utiliser le principe du moindre privilège - accorder uniquement les scopes API nécessaires
Surveiller les échecs d'authentification et implémenter des alertes
Implémenter une logique de réessai de connexion avec backoff exponentiel

Construire depuis les Sources (Optionnel)

La plupart des utilisateurs n'ont pas besoin de construire depuis les sources - le package npm inclut des bundles pré-construits. Cependant, si vous devez personnaliser ou construire le SDK vous-même:

# Cloner le dépôt
git clone https://github.com/optave/SDK-optave-client-integration.git
cd SDK-optave-client-integration/sdks/javascript

# Installer les dépendances
npm install

# Construire les bundles de production
npm run build:all:prod

Sorties de build:

dist/browser.mjs - Module ES navigateur
dist/server.mjs - Module ES serveur
dist/browser.umd.js - Bundle UMD navigateur
dist/server.umd.js - Bundle UMD serveur

Installation​

Installation Rapide​

Prérequis​

Dépendances de Performance Optionnelles​

Système de Build & Imports​

Builds Disponibles​

Sélection Automatique du Build (Recommandé)​

Sélection Explicite du Build​

Utilisation CDN (Navigateur Uniquement)​

Exemples Spécifiques aux Frameworks​

Configuration​

Options de Configuration​

Exemples de Configuration​

Configuration Navigateur (Pattern Token Provider)​

Configuration Serveur (Client Credentials)​

Configuration Serveur (Alternative Token Provider)​

Exemple de Configuration Complète (Serveur)​

Meilleures Pratiques de Sécurité​

Applications Navigateur​

Applications Serveur​

Construire depuis les Sources (Optionnel)​