@ourlu/assistant-sdk 0.2.0

package/README.md

@@ -0,0 +1,109 @@
+# Assistant SDK JS
+
+SDK JavaScript du widget assistant, maintenu dans `assistant-sdk-js`.
+
+## Mise à jour mission (2026-05-17)
+
+- 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.
+
+## Périmètre
+
+Ce package fournit:
+
+- 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 package n'écrit jamais dans `ourlu` directement. La copie vers le backend est pilotée côté consommateur via script dédié.
+
+## Arborescence réelle
+
+- `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*`.
+
+## API publique (ESM)
+
+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"`).
+
+Options principales `bootstrapWidgetRuntime`:
+
+- `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`).
+
+## Build, test, packaging
+
+```powershell
+npm ci
+npm run build
+npm run test
+npm run pack:check
+```
+
+Scripts disponibles (`package.json`):
+
+- `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`
+
+## Intégration avec `ourlu`
+
+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`
+
+Ces assets sont embarqués dans le binaire backend (`go:embed`) après synchronisation.
+
+### Mode workspace (développement local)
+
+1. builder le SDK dans ce dossier (`npm run build`);
+2. exécuter la synchronisation côté `ourlu`.
+
+Depuis la racine du workspace:
+
+```powershell
+.\ourlu\backend\scripts\sync-assistant-sdk-assets.ps1
+```
+
+Lock utilisé: `ourlu/backend/scripts/assistant-sdk.lock.json`
+(`workspaceDistDirectory=..\..\sdks\js\assistant-sdk-js\dist\iife`).
+
+### Mode npm (release versionnée)
+
+Le script de sync backend supporte `sourceMode=npm` via:
+
+- `ourlu/backend/scripts/assistant-sdk.lock.npm.example.json`
+- champs `registryUrl` et `npmAuthTokenEnvVar`
+
+## Contrat et compatibilité
+
+- contrat public SDK: `../../../docs/SDK_CONTRACT_V1.md`
+- changelog: `CHANGELOG.md`
+- stratégie de release: `docs/RELEASE_STRATEGY.md`
+
+Règle: toute rupture contractuelle sur les `data-*`, méthodes ou événements publics implique un changement majeur (`v2`).
+
+## CI/CD
+
+Workflow: `.github/workflows/sdk-ci-release.yml`
+
+- 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`.

package/dist/esm/index.js

@@ -0,0 +1,436 @@
+const DEFAULT_TIMEOUT_MS = 8000;
+const DEFAULT_CHAT_TIMEOUT_MS = 45000;
+
+class RuntimeUrlResolverManager {
+  resolveFromLoaderUrl(loaderUrl, fileName) {
+    if (!loaderUrl || typeof loaderUrl !== "string") return "";
+    try {
+      const fallbackBaseUrl =
+        typeof window !== "undefined" && window.location && window.location.href
+          ? window.location.href
+          : "http://localhost/";
+      const normalizedLoaderUrl = new URL(loaderUrl, fallbackBaseUrl);
+      const normalizedPath = normalizedLoaderUrl.pathname.replace(/\/[^/]*$/, "/");
+      return `${normalizedLoaderUrl.origin}${normalizedPath}${fileName}`;
+    } catch (_error) {
+      return "";
+    }
+  }
+
+  resolve(options) {
+    const loaderUrl = String(options?.loaderUrl || "").trim();
+    const uiUrl = String(options?.uiUrl || "").trim();
+    const engineUrl = String(options?.engineUrl || "").trim();
+    return {
+      loaderUrl,
+      uiUrl: uiUrl || this.resolveFromLoaderUrl(loaderUrl, "ui.v1.js"),
+      engineUrl: engineUrl || this.resolveFromLoaderUrl(loaderUrl, "engine.v1.js"),
+    };
+  }
+}
+
+class BrowserScriptLoaderManager {
+  loadScript(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+      const node = document.createElement("script");
+      let timeoutId = null;
+      node.src = url;
+      node.async = true;
+      node.onload = () => {
+        if (timeoutId) clearTimeout(timeoutId);
+        resolve();
+      };
+      node.onerror = () => {
+        if (timeoutId) clearTimeout(timeoutId);
+        reject(new Error(`Impossible de charger le script: ${url}`));
+      };
+      timeoutId = setTimeout(() => {
+        reject(new Error(`Timeout de chargement script: ${url}`));
+      }, timeoutMs);
+      document.head.appendChild(node);
+    });
+  }
+}
+
+class RuntimeBootstrapManager {
+  constructor(urlResolverManager, scriptLoaderManager) {
+    this.urlResolverManager = urlResolverManager;
+    this.scriptLoaderManager = scriptLoaderManager;
+  }
+
+  async loadRuntimeAssets(options) {
+    const resolvedUrls = this.urlResolverManager.resolve(options);
+    if (!resolvedUrls.uiUrl || !resolvedUrls.engineUrl) {
+      throw new Error("Urls runtime incomplètes (ui/engine).");
+    }
+    await this.scriptLoaderManager.loadScript(resolvedUrls.uiUrl, options?.timeoutMs);
+    await this.scriptLoaderManager.loadScript(resolvedUrls.engineUrl, options?.timeoutMs);
+    return resolvedUrls;
+  }
+
+  mountFromScript(scriptTag) {
+    const runtime = window.__CompanionWidgetRuntimeV1;
+    if (!runtime || typeof runtime.mountFromScript !== "function") {
+      throw new Error("Entrée runtime SDK absente.");
+    }
+    runtime.mountFromScript(scriptTag);
+  }
+}
+
+class SdkHttpTransportManager {
+  constructor({ fetchImpl = globalThis.fetch, headersProvider = null } = {}) {
+    this.fetchImpl = fetchImpl;
+    this.headersProvider = headersProvider;
+  }
+
+  buildHeaders(extraHeaders = {}) {
+    const resolvedHeaders = this.headersProvider ? this.headersProvider() : {};
+    return {
+      ...(resolvedHeaders && typeof resolvedHeaders === "object" ? resolvedHeaders : {}),
+      ...extraHeaders,
+    };
+  }
+
+  async fetchJson({ url, method = "GET", headers = {}, body = null, timeoutMs = DEFAULT_CHAT_TIMEOUT_MS }) {
+    const response = await this.fetchRaw({ url, method, headers, body, timeoutMs });
+    const contentType = String(response.headers.get("content-type") || "");
+    if (!contentType.includes("application/json")) {
+      throw new Error(`Réponse JSON attendue: ${url}`);
+    }
+    return response.json();
+  }
+
+  async fetchRaw({ url, method = "GET", headers = {}, body = null, timeoutMs = DEFAULT_CHAT_TIMEOUT_MS }) {
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error("API fetch indisponible pour le SDK.");
+    }
+    const abortController = new AbortController();
+    const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
+    try {
+      const response = await this.fetchImpl(url, {
+        method,
+        headers: this.buildHeaders(headers),
+        body,
+        signal: abortController.signal,
+      });
+      if (!response.ok) {
+        throw new Error(await this.resolveHttpError({ response, url, method }));
+      }
+      return response;
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new Error(`Timeout SDK après ${timeoutMs}ms`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  async resolveHttpError({ response, url, method }) {
+    const contentType = String(response.headers.get("content-type") || "");
+    if (contentType.includes("application/json")) {
+      const payload = await response.json().catch(() => null);
+      const message = String(payload?.error || payload?.message || "").trim();
+      if (message) {
+        return `${message} [${method} ${url}]`;
+      }
+    }
+    return `Erreur HTTP SDK (${response.status}) [${method} ${url}]`;
+  }
+}
+
+class SseEventDecoderManager {
+  decodeChunk(buffer, incomingChunk) {
+    const joinedBuffer = `${buffer}${incomingChunk}`;
+    const eventBlocks = joinedBuffer.split("\n\n");
+    const remainingBuffer = eventBlocks.pop() || "";
+    const decodedEvents = eventBlocks.map((eventBlock) => this.decodeBlock(eventBlock)).filter(Boolean);
+    return {
+      remainingBuffer,
+      decodedEvents,
+    };
+  }
+
+  decodeLastBuffer(buffer) {
+    if (!String(buffer || "").trim()) {
+      return [];
+    }
+    const decodedEvent = this.decodeBlock(buffer);
+    return decodedEvent ? [decodedEvent] : [];
+  }
+
+  decodeBlock(eventBlock) {
+    const lines = String(eventBlock || "").split("\n");
+    let eventName = "message";
+    const dataLines = [];
+    lines.forEach((line) => {
+      if (line.startsWith("event:")) {
+        eventName = line.slice("event:".length).trim() || "message";
+      } else if (line.startsWith("data:")) {
+        dataLines.push(line.slice("data:".length).trim());
+      }
+    });
+    if (dataLines.length === 0) {
+      return null;
+    }
+    const rawData = dataLines.join("\n");
+    if (rawData === "[DONE]") {
+      return { eventName: "done", data: { raw: "[DONE]" } };
+    }
+    try {
+      return { eventName, data: JSON.parse(rawData) };
+    } catch (_error) {
+      return { eventName, data: { raw: rawData } };
+    }
+  }
+}
+
+class SdkEndpointPathResolverManager {
+  resolve(options = {}) {
+    const apiBaseUrl = this.resolveApiBaseUrl(options.apiBaseUrl);
+    const bootstrapEndpoint = this.resolveAbsoluteUrl({
+      baseUrl: apiBaseUrl,
+      endpoint: options.bootstrapEndpoint,
+      defaultPath: "/v1/occe/chat/bootstrap",
+    });
+    const sessionsEndpoint = this.resolveAbsoluteUrl({
+      baseUrl: apiBaseUrl,
+      endpoint: options.sessionsEndpoint,
+      defaultPath: "/v1/occe/chat/sessions",
+    });
+    return {
+      apiBaseUrl,
+      bootstrapEndpoint,
+      sessionsEndpoint,
+    };
+  }
+
+  resolveApiBaseUrl(rawBaseUrl) {
+    const trimmedBaseUrl = String(rawBaseUrl || "").trim();
+    const fallbackBaseUrl = this.resolveBrowserOrigin();
+    return (trimmedBaseUrl || fallbackBaseUrl).replace(/\/+$/, "");
+  }
+
+  resolveBrowserOrigin() {
+    if (typeof window !== "undefined" && window.location && window.location.origin) {
+      return window.location.origin;
+    }
+    return "http://localhost";
+  }
+
+  resolveAbsoluteUrl({ baseUrl, endpoint, defaultPath }) {
+    const explicitEndpoint = String(endpoint || "").trim();
+    if (!explicitEndpoint) {
+      return `${baseUrl}${defaultPath}`;
+    }
+    if (/^https?:\/\//i.test(explicitEndpoint)) {
+      return explicitEndpoint;
+    }
+    const normalizedPath = explicitEndpoint.startsWith("/") ? explicitEndpoint : `/${explicitEndpoint}`;
+    return `${baseUrl}${normalizedPath}`;
+  }
+}
+
+class SdkHeadlessChatClientManager {
+  constructor(options = {}) {
+    this.endpointResolverManager = new SdkEndpointPathResolverManager();
+    this.sseDecoderManager = new SseEventDecoderManager();
+    this.transportManager = new SdkHttpTransportManager({
+      fetchImpl: options.fetchImpl,
+      headersProvider: options.headersProvider,
+    });
+    this.timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_CHAT_TIMEOUT_MS;
+    this.tenantId = String(options.tenantId || "").trim();
+    this.widgetKey = String(options.widgetKey || "").trim();
+    this.targetLanguage = String(options.targetLanguage || "").trim().toLowerCase();
+    if (!this.targetLanguage) {
+      throw new Error("targetLanguage requis en mode temporal-only.");
+    }
+    const resolvedEndpoints = this.endpointResolverManager.resolve(options);
+    this.bootstrapEndpoint = resolvedEndpoints.bootstrapEndpoint;
+    this.sessionsEndpoint = resolvedEndpoints.sessionsEndpoint;
+    this.sessionBootstrapToken = String(options.sessionBootstrapToken || "").trim();
+    this.useBootstrapAuthorization = options.useBootstrapAuthorization !== false;
+    this.sessionId = "";
+  }
+
+  resetSession() {
+    this.sessionId = "";
+  }
+
+  async runChat({ content, messagePayload = {}, onEvent } = {}) {
+    const safeContent = String(content || "").trim();
+    if (!safeContent) {
+      throw new Error("Le contenu du message SDK est vide.");
+    }
+    const sessionId = await this.ensureSession();
+    await this.sendMessage({ sessionId, content: safeContent, messagePayload });
+    const streamResult = await this.streamSession({ sessionId, onEvent });
+    return {
+      sessionId,
+      ...streamResult,
+    };
+  }
+
+  async ensureSession() {
+    if (this.sessionId) {
+      return this.sessionId;
+    }
+    await this.ensureBootstrapToken();
+    const payload = await this.transportManager.fetchJson({
+      url: this.sessionsEndpoint,
+      method: "POST",
+      headers: this.buildHeaders({ "Content-Type": "application/json" }),
+      body: "{}",
+      timeoutMs: this.timeoutMs,
+    });
+    const sessionId = String(payload?.session_id || payload?.id || "").trim();
+    if (!sessionId) {
+      throw new Error("Session SDK introuvable dans la réponse.");
+    }
+    this.sessionId = sessionId;
+    return this.sessionId;
+  }
+
+  async ensureBootstrapToken() {
+    if (this.sessionBootstrapToken) {
+      return this.sessionBootstrapToken;
+    }
+    const payload = await this.transportManager.fetchJson({
+      url: this.bootstrapEndpoint,
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        tenant_id: this.tenantId,
+        public_widget_key: this.widgetKey,
+        origin: this.resolveOrigin(),
+      }),
+      timeoutMs: this.timeoutMs,
+    });
+    this.sessionBootstrapToken = String(payload?.session_bootstrap_token || payload?.session_token || "").trim();
+    return this.sessionBootstrapToken;
+  }
+
+  resolveOrigin() {
+    if (typeof window !== "undefined" && window.location && window.location.origin) {
+      return window.location.origin;
+    }
+    return "http://localhost";
+  }
+
+  buildHeaders(extraHeaders = {}) {
+    const headers = {
+      ...extraHeaders,
+    };
+    const widgetOrigin = this.resolveOrigin();
+    if (widgetOrigin) {
+      headers["X-Widget-Origin"] = widgetOrigin;
+    }
+    if (this.widgetKey) {
+      headers["X-Widget-Key"] = this.widgetKey;
+    }
+    if (this.tenantId) {
+      headers["X-Tenant-ID"] = this.tenantId;
+    }
+    if (this.targetLanguage) {
+      headers["X-Target-Language"] = this.targetLanguage;
+    }
+    if (this.useBootstrapAuthorization && this.sessionBootstrapToken) {
+      headers.Authorization = `Bearer ${this.sessionBootstrapToken}`;
+    }
+    return headers;
+  }
+
+  async sendMessage({ sessionId, content, messagePayload = {} }) {
+    const body = JSON.stringify({
+      content,
+      ...((messagePayload && typeof messagePayload === "object") ? messagePayload : {}),
+    });
+    await this.transportManager.fetchRaw({
+      url: `${this.sessionsEndpoint}/${sessionId}/messages`,
+      method: "POST",
+      headers: this.buildHeaders({ "Content-Type": "application/json" }),
+      body,
+      timeoutMs: this.timeoutMs,
+    });
+  }
+
+  async streamSession({ sessionId, onEvent } = {}) {
+    const response = await this.transportManager.fetchRaw({
+      url: `${this.sessionsEndpoint}/${sessionId}/stream`,
+      method: "GET",
+      headers: this.buildHeaders(),
+      timeoutMs: this.timeoutMs,
+    });
+    if (!response.body) {
+      throw new Error("Flux SDK indisponible (body absent).");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    const streamEvents = [];
+    let finalEventPayload = null;
+    let buffer = "";
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) {
+        const trailingEvents = this.sseDecoderManager.decodeLastBuffer(buffer);
+        trailingEvents.forEach((streamEvent) => {
+          finalEventPayload = this.emitStreamEvent({ streamEvent, onEvent, streamEvents, finalEventPayload });
+        });
+        break;
+      }
+      const chunk = decoder.decode(value, { stream: true });
+      const decodedChunk = this.sseDecoderManager.decodeChunk(buffer, chunk);
+      buffer = decodedChunk.remainingBuffer;
+      decodedChunk.decodedEvents.forEach((streamEvent) => {
+        finalEventPayload = this.emitStreamEvent({ streamEvent, onEvent, streamEvents, finalEventPayload });
+      });
+    }
+    return {
+      events: streamEvents,
+      finalEventPayload,
+    };
+  }
+
+  emitStreamEvent({ streamEvent, onEvent, streamEvents, finalEventPayload }) {
+    const normalizedEvent = {
+      eventName: streamEvent.eventName,
+      data: streamEvent.data,
+      receivedAt: new Date().toISOString(),
+    };
+    streamEvents.push(normalizedEvent);
+    if (typeof onEvent === "function") {
+      onEvent(normalizedEvent);
+    }
+    const eventName = String(normalizedEvent.eventName || "").toLowerCase();
+    if (eventName.includes("final") || eventName.includes("done")) {
+      return normalizedEvent.data;
+    }
+    return finalEventPayload;
+  }
+}
+
+const runtimeBootstrapManager = new RuntimeBootstrapManager(
+  new RuntimeUrlResolverManager(),
+  new BrowserScriptLoaderManager(),
+);
+
+export const sdkVersion = "v1";
+export {
+  RuntimeUrlResolverManager,
+  BrowserScriptLoaderManager,
+  RuntimeBootstrapManager,
+  SdkHeadlessChatClientManager,
+  SdkHttpTransportManager,
+  SdkEndpointPathResolverManager,
+  SseEventDecoderManager,
+};
+
+export async function bootstrapWidgetRuntime(options) {
+  return runtimeBootstrapManager.loadRuntimeAssets(options || {});
+}
+
+export function mountWidgetFromScript(scriptTag) {
+  return runtimeBootstrapManager.mountFromScript(scriptTag);
+}