@ourlu/assistant-sdk 0.2.0 → 0.2.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ourlu/assistant-sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "SDK JavaScript pour l'assistant conversationnel Ourlu — widget intégrable pour les mairies.",
   "type": "module",
   "private": false,