@ourlu/assistant-sdk 0.2.0 → 0.2.3

package/README.md

@@ -1,109 +1,156 @@
-# Assistant SDK JS
+# @ourlu/assistant-sdk
 
-SDK JavaScript du widget assistant, maintenu dans `assistant-sdk-js`.
+SDK JavaScript pour intégrer le chatbot IA Ourlu sur les sites web de collectivités.
 
-## Mise à jour mission (2026-05-17)
+## Installation
 
-- Aucun changement de périmètre fonctionnel SDK lié à la rationalisation microservices backend.
-- Le SDK reste découplé de Temporal et des choix d'orchestration backend.
-- Priorité conservée: stabilité contractuelle (`SDK_CONTRACT_V1`) et diffusion versionnée.
+### Copier-coller (recommandé)
 
-## Périmètre
+Ajoutez ce snippet avant la balise `</body>` de votre site :
 
-Ce package fournit:
+```html
+<script
+  src="https://occe.ourlu.fr/v1/widget/runtime/loader.v1.js"
+  data-tenant-id="votre-identifiant-mairie"
+  data-widget-key="wpk_votre_cle_publique"
+  data-api-base-url="https://occe.ourlu.fr"
+  async
+></script>
+```
 
-- le loader IIFE (`loader.v1.js`) pour intégration `<script ...>`;
-- les runtimes UI/engine (`ui.v1.js`, `engine.v1.js`);
-- une API ESM (`dist/esm/index.js`) pour bootstrap programmatique.
+Le chatbot apparaît automatiquement en bas à droite de votre site.
 
-Le package n'écrit jamais dans `ourlu` directement. La copie vers le backend est pilotée côté consommateur via script dédié.
+### npm (usage programmatique)
 
-## Arborescence réelle
+```bash
+npm i @ourlu/assistant-sdk
+```
 
-- `src/loader/loader.v1.js`: chargeur principal exécuté côté navigateur.
-- `src/runtime/loader.runtime.ui.v1.js`: UI widget, rendu, interactions.
-- `src/runtime/loader.runtime.engine.v1.js`: appels API chat/audio + orchestration runtime.
-- `src/esm/index.js`: helpers publics (`bootstrapWidgetRuntime`, `mountWidgetFromScript`) et managers ESM.
-- `scripts/build.mjs`: build par copie contrôlée `src -> dist`.
-- `tests/runtime-url-resolver.test.mjs`: tests Node du resolver d'URLs runtime.
-- `.github/workflows/sdk-ci-release.yml`: pipeline CI + publication sur tags `v*`.
+```javascript
+import { bootstrapWidgetRuntime } from '@ourlu/assistant-sdk';
 
-## API publique (ESM)
+bootstrapWidgetRuntime({
+  loaderUrl: 'https://occe.ourlu.fr/v1/widget/runtime/loader.v1.js'
+});
+```
 
-Exports (`src/esm/index.js`):
+---
 
-- `bootstrapWidgetRuntime(options)`: charge `ui.v1.js` + `engine.v1.js`.
-- `mountWidgetFromScript(scriptTag)`: délègue au runtime global `window.__CompanionWidgetRuntimeV1`.
-- `RuntimeUrlResolverManager`
-- `BrowserScriptLoaderManager`
-- `RuntimeBootstrapManager`
-- `sdkVersion` (`"v1"`).
+## Configuration
 
-Options principales `bootstrapWidgetRuntime`:
+| Attribut | Requis | Description |
+|----------|--------|-------------|
+| `data-tenant-id` | ✅ | Identifiant de votre collectivité |
+| `data-widget-key` | ✅ | Clé publique du widget (fournie dans l'espace admin) |
+| `data-api-base-url` | ✅ | URL de la plateforme (`https://occe.ourlu.fr`) |
+| `data-turnstile-site-key` | ❌ | Clé Cloudflare Turnstile pour protection anti-bot |
 
-- `loaderUrl` (recommandé) pour résoudre automatiquement `ui.v1.js` et `engine.v1.js`;
-- `uiUrl` / `engineUrl` (optionnels) pour surcharger explicitement;
-- `timeoutMs` (optionnel, défaut interne `8000`).
+Le thème (couleurs, mascotte, position, textes) est géré automatiquement depuis votre espace d'administration Ourlu. Aucune modification du code d'intégration n'est nécessaire après un changement de design.
 
-## Build, test, packaging
+---
 
-```powershell
-npm ci
-npm run build
-npm run test
-npm run pack:check
-```
+## Compatibilité
+
+### CMS & plateformes
+
+WordPress, Drupal, SPIP, Joomla, TYPO3, Wix, Squarespace, Webflow, Shopify, et tout site acceptant un tag `<script>`.
+
+### Frameworks JavaScript
+
+React, Vue, Svelte, Angular, Next.js, Nuxt, Astro, Remix, SvelteKit.
+
+### Sites statiques
 
-Scripts disponibles (`package.json`):
+HTML pur, Jekyll, Hugo, Eleventy, Cloudflare Pages, Netlify, Vercel, GitHub Pages.
 
-- `build`: `node ./scripts/build.mjs`
-- `test`: `node --test ./tests/*.test.mjs`
-- `prepack`: build + test
-- `pack:check`: `npm pack --dry-run`
-- `publish:dry-run`: `npm publish --dry-run`
+### Navigateurs supportés
 
-## Intégration avec `ourlu`
+- Chrome 66+
+- Firefox 60+
+- Safari 12+
+- Edge 79+
+- Mobile (iOS Safari, Chrome Android)
 
-Le backend `ourlu` sert les assets runtime via:
+---
 
-- `GET /v1/widget/runtime/loader.v1.js`
-- `GET /v1/widget/runtime/ui.v1.js`
-- `GET /v1/widget/runtime/engine.v1.js`
+## Fonctionnalités
 
-Ces assets sont embarqués dans le binaire backend (`go:embed`) après synchronisation.
+- 💬 Chat textuel avec assistant IA en temps réel (streaming SSE)
+- 🎙️ Entrée vocale avec transcription automatique
+- 🎨 Thème personnalisable (couleurs, position, mascotte)
+- 🌓 Mode sombre automatique (suit les préférences système)
+- 🛡️ Protection anti-bot Cloudflare Turnstile (optionnelle)
+- 🔒 Authentification JWT automatique
+- ♿ Accessible (navigation clavier, échappement pour fermer)
+- 📱 Responsive (mobile et desktop)
 
-### Mode workspace (développement local)
+---
 
-1. builder le SDK dans ce dossier (`npm run build`);
-2. exécuter la synchronisation côté `ourlu`.
+## Protection anti-bot (optionnelle)
 
-Depuis la racine du workspace:
+Pour activer Cloudflare Turnstile :
 
-```powershell
-.\ourlu\backend\scripts\sync-assistant-sdk-assets.ps1
+```html
+<script
+  src="https://occe.ourlu.fr/v1/widget/runtime/loader.v1.js"
+  data-tenant-id="votre-mairie"
+  data-widget-key="wpk_..."
+  data-api-base-url="https://occe.ourlu.fr"
+  data-turnstile-site-key="0x4AAAAAAA..."
+  async
+></script>
 ```
 
-Lock utilisé: `ourlu/backend/scripts/assistant-sdk.lock.json`
-(`workspaceDistDirectory=..\..\sdks\js\assistant-sdk-js\dist\iife`).
+Le captcha est invisible dans 99% des cas. Sans la clé Turnstile, le chatbot fonctionne normalement sans protection anti-bot.
+
+---
+
+## API publique (ESM)
+
+Pour une intégration programmatique avancée :
+
+```javascript
+import {
+  bootstrapWidgetRuntime,
+  mountWidgetFromScript,
+  sdkVersion
+} from '@ourlu/assistant-sdk';
+```
+
+| Export | Description |
+|--------|-------------|
+| `bootstrapWidgetRuntime(options)` | Charge et initialise le widget |
+| `mountWidgetFromScript(scriptTag)` | Monte le widget depuis un élément script existant |
+| `sdkVersion` | Version du SDK (`"v1"`) |
+
+### Options `bootstrapWidgetRuntime`
+
+| Option | Description | Défaut |
+|--------|-------------|--------|
+| `loaderUrl` | URL du loader (résout automatiquement UI + engine) | — |
+| `uiUrl` | URL explicite du runtime UI | Auto |
+| `engineUrl` | URL explicite du runtime engine | Auto |
+| `timeoutMs` | Timeout de chargement en ms | `8000` |
 
-### Mode npm (release versionnée)
+---
 
-Le script de sync backend supporte `sourceMode=npm` via:
+## Sécurité & RGPD
 
-- `ourlu/backend/scripts/assistant-sdk.lock.npm.example.json`
-- champs `registryUrl` et `npmAuthTokenEnvVar`
+- Aucun cookie tiers installé
+- Anonymisation native des données personnelles (PII masking)
+- Compatible Content Security Policy (CSP) stricte
+- Option auto-hébergement des fichiers JS
+- Option reverse-proxy pour anonymisation IP
 
-## Contrat et compatibilité
+---
 
-- contrat public SDK: `../../../docs/SDK_CONTRACT_V1.md`
-- changelog: `CHANGELOG.md`
-- stratégie de release: `docs/RELEASE_STRATEGY.md`
+## Support
 
-Règle: toute rupture contractuelle sur les `data-*`, méthodes ou événements publics implique un changement majeur (`v2`).
+- Documentation : espace admin Ourlu > Intégration
+- Contact technique : integration@ourlu.fr
 
-## CI/CD
+---
 
-Workflow: `.github/workflows/sdk-ci-release.yml`
+## Licence
 
-- job `validate` sur branches/PR: `npm ci`, `npm run test`, `npm run build`, `npm run pack:check`;
-- job `publish` sur tag `v*`: `npm publish --access restricted` avec `NPM_TOKEN`.
+Propriétaire — Ourlu SAS. Usage réservé aux collectivités clientes.

package/dist/esm/index.js

@@ -69,7 +69,7 @@ class RuntimeBootstrapManager {
   }
 
   mountFromScript(scriptTag) {
-    const runtime = window.__CompanionWidgetRuntimeV1;
+    const runtime = window.__OurluWidgetRuntimeV1;
     if (!runtime || typeof runtime.mountFromScript !== "function") {
       throw new Error("Entrée runtime SDK absente.");
     }

package/dist/iife/audio.v1.95146620.js

@@ -0,0 +1,179 @@
+(function() {
+  "use strict";
+  var runtime = window.__OurluWidgetRuntimeV1 || (window.__OurluWidgetRuntimeV1 = {});
+  if (!runtime.utils) {
+    throw new Error("Widget runtime utils module must be loaded first.");
+  }
+
+  var mergeTranscript = runtime.utils.mergeTranscript;
+  var resolveRecorderMimeType = runtime.utils.resolveRecorderMimeType;
+  var encodeArrayBufferToBase64 = runtime.utils.encodeArrayBufferToBase64;
+
+  function WidgetAudioManager(state, api, ui) {
+    this.state = state;
+    this.api = api;
+    this.ui = ui;
+    this.stream = null;
+    this.recorder = null;
+    this.chunks = [];
+    this.stopDraftStream = null;
+    this.activeAudioSessionId = "";
+    this.cleanupTimer = null;
+    this._starting = false;
+    this._stopping = false;
+  }
+
+  WidgetAudioManager.prototype.isSupported = function() {
+    return !!(navigator.mediaDevices && navigator.mediaDevices.getUserMedia && typeof MediaRecorder !== "undefined");
+  };
+
+  WidgetAudioManager.prototype.toggle = async function() {
+    if (this._starting || this._stopping) return;
+    if (this.state.listening) return this.stop();
+    return this.start();
+  };
+
+  WidgetAudioManager.prototype.start = async function() {
+    if (!this.isSupported() || this.state.sending || this._starting || this._stopping) return;
+    this._starting = true;
+    this.ui.setMicListening(true);
+    try {
+      this.ui.showError("");
+      this.clearDraftCleanup();
+      if (this.activeAudioSessionId && this.state.sessionId) {
+        try {
+          await this.api.closeAudioSession(this.state.sessionId, this.activeAudioSessionId);
+        } catch (_) { /* best-effort */ }
+        this.activeAudioSessionId = "";
+      }
+      var sessionId = await this.api.ensureSession();
+      if (this.stopDraftStream) this.stopDraftStream();
+      this.stopDraftStream = await this.api.streamAudioDraft(sessionId, {
+        onDelta: this.handleDraftDelta.bind(this),
+        onComplete: this.handleDraftComplete.bind(this),
+        onError: this.handleDraftError.bind(this),
+        onTransportError: this.handleDraftTransportError.bind(this)
+      });
+      var audioSession = await this.api.startAudioSession(sessionId);
+      this.activeAudioSessionId = audioSession.audio_session_id || "";
+      this.stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      this.chunks = [];
+      var mimeType = resolveRecorderMimeType();
+      this.recorder = new MediaRecorder(this.stream, mimeType ? { mimeType: mimeType } : {});
+      var self = this;
+      this.recorder.ondataavailable = function(event) {
+        if (event.data && event.data.size > 0) self.chunks.push(event.data);
+      };
+      this.recorder.start(250);
+      this.state.listening = true;
+    } catch (error) {
+      this.cleanupMedia();
+      this.activeAudioSessionId = "";
+      this.state.listening = false;
+      this.ui.setMicListening(false);
+      this.ui.showError("Erreur démarrage audio : " + (error.message || error));
+    } finally {
+      this._starting = false;
+    }
+  };
+
+  WidgetAudioManager.prototype.stop = async function() {
+    if (!this.state.listening || this._stopping) return;
+    this._stopping = true;
+    this.state.listening = false;
+    this.ui.setMicListening(false);
+    var sessionId = this.state.sessionId;
+    var audioSessionId = this.activeAudioSessionId;
+    try {
+      var blob = await this.stopRecorder();
+      if (blob && blob.size > 0 && sessionId && audioSessionId) {
+        var base64 = encodeArrayBufferToBase64(await blob.arrayBuffer());
+        await this.api.sendAudioChunk(sessionId, audioSessionId, base64);
+      }
+      if (sessionId && audioSessionId) await this.api.closeAudioSession(sessionId, audioSessionId);
+    } catch (error) {
+      this.ui.showError("Erreur fermeture audio : " + (error.message || error));
+    } finally {
+      this.activeAudioSessionId = "";
+      this._stopping = false;
+      this.scheduleDraftCleanup();
+    }
+  };
+
+  WidgetAudioManager.prototype.stopRecorder = function() {
+    var self = this;
+    if (!this.recorder) {
+      this.cleanupMedia();
+      return Promise.resolve(new Blob());
+    }
+    return new Promise(function(resolve) {
+      var recorder = self.recorder;
+      function done() {
+        var blob = new Blob(self.chunks, { type: recorder.mimeType || "audio/webm" });
+        self.cleanupMedia();
+        resolve(blob);
+      }
+      if (recorder.state === "inactive") return done();
+      recorder.addEventListener("stop", done, { once: true });
+      recorder.stop();
+    });
+  };
+
+  WidgetAudioManager.prototype.cleanupMedia = function() {
+    if (this.recorder) {
+      this.recorder.ondataavailable = null;
+      this.recorder = null;
+    }
+    if (this.stream) {
+      this.stream.getTracks().forEach(function(track) { track.stop(); });
+      this.stream = null;
+    }
+    this.chunks = [];
+  };
+
+  WidgetAudioManager.prototype.handleDraftDelta = function(payload) {
+    if (!payload || !payload.delta) return;
+    this.ui.setInput(mergeTranscript(this.ui.inputValue(), payload.delta));
+  };
+
+  WidgetAudioManager.prototype.handleDraftComplete = function(payload) {
+    if (payload && payload.text) this.ui.setInput(String(payload.text).trim());
+    this.scheduleDraftCleanup();
+  };
+
+  WidgetAudioManager.prototype.handleDraftError = function(payload) {
+    this.ui.showError((payload && payload.message) || "Erreur transcription audio");
+    this.scheduleDraftCleanup();
+  };
+
+  WidgetAudioManager.prototype.isExpectedStreamAbortMessage = function(message) {
+    var normalized = String(message || "").toLowerCase();
+    return normalized.indexOf("aborted") !== -1 ||
+      normalized.indexOf("aborterror") !== -1 ||
+      normalized.indexOf("body stream buffer was aborted") !== -1 ||
+      normalized.indexOf("the operation was aborted") !== -1;
+  };
+
+  WidgetAudioManager.prototype.handleDraftTransportError = function(message) {
+    if (this.isExpectedStreamAbortMessage(message)) return;
+    this.ui.showError(message || "Erreur stream audio");
+  };
+
+  WidgetAudioManager.prototype.clearDraftCleanup = function() {
+    if (!this.cleanupTimer) return;
+    clearTimeout(this.cleanupTimer);
+    this.cleanupTimer = null;
+  };
+
+  WidgetAudioManager.prototype.scheduleDraftCleanup = function() {
+    var self = this;
+    this.clearDraftCleanup();
+    this.cleanupTimer = setTimeout(function() {
+      if (self.stopDraftStream) self.stopDraftStream();
+      self.stopDraftStream = null;
+      self.cleanupTimer = null;
+    }, 3000);
+  };
+
+  runtime.WidgetAudioManager = WidgetAudioManager;
+})();

package/dist/iife/audio.v1.js

@@ -1,6 +1,6 @@
 (function() {
   "use strict";
-  var runtime = window.__CompanionWidgetRuntimeV1 || (window.__CompanionWidgetRuntimeV1 = {});
+  var runtime = window.__OurluWidgetRuntimeV1 || (window.__OurluWidgetRuntimeV1 = {});
   if (!runtime.utils) {
     throw new Error("Widget runtime utils module must be loaded first.");
   }