@ephia/dova-sdk 1.0.0

package/src/react/provider/EphiaProvider.tsx

@@ -0,0 +1,373 @@
+"use client";
+
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import type { EphiaServerEvent } from "ephia-protocol";
+import { EphiaAudioClient } from "../../core/client/EphiaAudioClient";
+import type { EphiaAudioClientOptions } from "../../core/client/EphiaAudioClient";
+import type { EphiaStartOptions } from "../../core/client/client-options";
+import { mapTransportStateToConnectionState } from "../../core/connection/connection-state";
+import { TranscriptApplier } from "../../core/runtime/TranscriptApplier";
+import { TargetManager } from "../../core/targets/TargetManager";
+import { createEphiaStore } from "../store/create-ephia-store";
+import type { EphiaStore } from "../store/create-ephia-store";
+import type { EphiaStatus } from "../store/types";
+import {
+  EphiaContext,
+  type EphiaProviderConfig,
+} from "./EphiaContext";
+import {
+  EphiaInternalContext,
+  type EphiaInternalContextValue,
+} from "./EphiaInternalContext";
+import { ephiaClientConfigSchema } from "../../shared/config/schema";
+import { resolveEphiaSdkApiUrl } from "../../shared/config/endpoint";
+import { dbgState } from "../../debug/sdk-debug-collector";
+
+export interface EphiaProviderProps {
+  children: React.ReactNode;
+
+  apiUrl?: string;
+  apiKey?: string;
+  bearerToken?: string;
+  clientType?: string;
+
+  transport?: EphiaAudioClientOptions["transport"];
+
+  options?: {
+    language?: string;
+    medicalDomain?: string;
+    sessionOptions?: EphiaAudioClientOptions["sessionOptions"];
+  };
+
+  onError?: (error: { code: string; message: string }) => void;
+  onStatusChange?: (status: EphiaStatus) => void;
+
+  preloadSession?: boolean;
+  preloadInitialTargetId?: string;
+  noiseFilter?: boolean;
+  vadGate?: boolean;
+  audioInputDeviceId?: string;
+}
+
+async function preloadWithRetry(
+  client: EphiaAudioClient,
+  signal: AbortSignal,
+  options?: EphiaStartOptions,
+  maxRetries = 3
+): Promise<void> {
+  for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+    if (signal.aborted) return;
+    try {
+      await client.preload(options, signal);
+      return;
+    } catch {
+      if (attempt < maxRetries - 1 && !signal.aborted) {
+        await new Promise<void>((resolve) => {
+          setTimeout(resolve, 500 * 2 ** attempt);
+        });
+      }
+    }
+  }
+}
+
+function mapClientStatus(
+  clientStatus: string,
+  currentStatus: EphiaStatus
+): EphiaStatus {
+  switch (clientStatus) {
+    case "recording":
+      return "recording";
+    case "creating_session":
+    case "connecting_transport":
+    case "connecting":
+    case "ready":
+      if (currentStatus === "recording") return "recording";
+      if (currentStatus === "processing") return "processing";
+      return "idle";
+    case "paused":
+      if (currentStatus === "processing") return "processing";
+      return "idle";
+    case "finalizing":
+      if (currentStatus === "recording" || currentStatus === "processing") {
+        return "processing";
+      }
+      return "idle";
+    case "ended":
+      return "idle";
+    case "error":
+      return "error";
+    case "idle":
+    case "disposed":
+    case "disconnected":
+      if (currentStatus === "processing") return "processing";
+      return "idle";
+    default:
+      return currentStatus;
+  }
+}
+
+export function EphiaProvider({
+  children,
+  apiUrl,
+  apiKey,
+  bearerToken,
+  clientType,
+  transport,
+  options = {},
+  onError,
+  onStatusChange,
+  preloadSession = true,
+  preloadInitialTargetId,
+  noiseFilter = false,
+  vadGate = true,
+  audioInputDeviceId,
+}: EphiaProviderProps) {
+  const resolvedApiUrl = useMemo(
+    () => resolveEphiaSdkApiUrl(apiUrl),
+    [apiUrl],
+  );
+
+  const storeRef = useRef<EphiaStore | null>(null);
+  const clientRef = useRef<EphiaAudioClient | null>(null);
+  const targetManagerRef = useRef<TargetManager | null>(null);
+  const applierRef = useRef<TranscriptApplier | null>(null);
+  const applyServerEventRef = useRef<(event: EphiaServerEvent) => void>(() => {});
+  const [clientEpoch, setClientEpoch] = useState(0);
+
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+  const onStatusChangeRef = useRef(onStatusChange);
+  onStatusChangeRef.current = onStatusChange;
+
+  const sessionOptionsKey = useMemo(
+    () => JSON.stringify(options.sessionOptions ?? null),
+    [options.sessionOptions],
+  );
+
+  if (!storeRef.current) {
+    storeRef.current = createEphiaStore();
+  }
+  const store = storeRef.current;
+
+  useEffect(() => {
+    const cfgValidation = ephiaClientConfigSchema.partial().safeParse({
+      apiUrl: resolvedApiUrl,
+      apiKey,
+    });
+    if (!cfgValidation.success) {
+      console.warn("[ephia] invalid provider config:", cfgValidation.error.issues);
+    }
+
+    const client = new EphiaAudioClient({
+      apiUrl: resolvedApiUrl,
+      apiKey,
+      bearerToken,
+      clientType,
+      transport,
+      noiseFilter,
+      vadGate,
+      sessionOptions: options.sessionOptions,
+      onStateChange: (clientState) => {
+        const currentStatus = store.getState().status;
+        const nextStatus = mapClientStatus(clientState.status, currentStatus);
+        if (nextStatus !== currentStatus) {
+          store.getState()._setStatus(nextStatus);
+          onStatusChangeRef.current?.(nextStatus);
+        }
+        if (clientState.sessionId !== store.getState().sessionId) {
+          store.getState()._setSessionId(clientState.sessionId);
+        }
+        if (clientState.error) {
+          store.getState()._setError(clientState.error);
+        }
+      },
+      onAudioState: (audioState) => {
+        store.getState()._setAudio({ ...store.getState().audio, ...audioState });
+      },
+      onError: (err) => {
+        store.getState()._setError(err);
+        store.getState()._setStatus("error");
+        onErrorRef.current?.(err);
+      },
+    });
+
+    const targetManager = new TargetManager({
+      sendMessage: (message) => client.sendMessage(message as any),
+      onActiveTargetChange: (targetId) => store.getState()._setActiveTarget(targetId),
+      onTargetRegistered: (targetId) => {
+        // Flush pending events for this target when it becomes available.
+        const applierInstance = applierRef.current;
+        if (applierInstance) {
+          applierInstance.flushPendingEvents(targetId);
+        }
+      },
+    });
+    targetManagerRef.current = targetManager;
+    clientRef.current = client;
+    setClientEpoch((epoch) => epoch + 1);
+
+    dbgState("sdk.store", store.getState());
+    dbgState("sdk.client", client.getDebugSnapshot());
+
+    const preloadAbort = new AbortController();
+    if (preloadSession) {
+      preloadWithRetry(
+        client,
+        preloadAbort.signal,
+        preloadInitialTargetId ? { initialTargetId: preloadInitialTargetId } : undefined,
+      ).catch(() => {});
+    }
+
+    const warmupEvents = [
+      "pointerover",
+      "pointerdown",
+      "focusin",
+      "keydown",
+      "touchstart",
+    ] as const;
+    const _isSafari =
+      typeof navigator !== "undefined" &&
+      /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
+    const triggerWarmup = (_event?: Event) => {
+      warmupEvents.forEach((evt) =>
+        document.removeEventListener(evt, triggerWarmup)
+      );
+      if (!_isSafari) {
+        client.warmupMic().catch(() => {});
+      }
+    };
+    warmupEvents.forEach((evt) =>
+      document.addEventListener(evt, triggerWarmup, { once: true })
+    );
+
+    const unsubPageHide = client.registerPageHideStop();
+
+    const unsubTransport = client.onTransportState((transportState) => {
+      const prev = store.getState().connection;
+      store.getState()._setConnection(
+        mapTransportStateToConnectionState(transportState, prev)
+      );
+    });
+
+    const unsubStore = store.subscribe((state) => {
+      dbgState("sdk.store", state);
+    });
+
+    const mountedActiveId = store.getState().activeTargetId;
+    if (mountedActiveId) targetManager.setActive(mountedActiveId);
+
+    const applier = new TranscriptApplier({ targetManager });
+    applierRef.current = applier;
+    applyServerEventRef.current = (event) => applier.handleEvent(event);
+    const unsubServerEvent = client.onServerEvent((event) => applier.handleEvent(event));
+
+    // Highlight the active target via data-ephia-target-active
+    let prevActiveId: string | null = store.getState().activeTargetId;
+    if (prevActiveId) {
+      targetManager.get(prevActiveId)?.element?.setAttribute("data-ephia-target-active", "true");
+    }
+    const unsubActive = store.subscribe((state) => {
+      if (state.activeTargetId === prevActiveId) return;
+
+      if (prevActiveId) {
+        targetManager.get(prevActiveId)?.element?.removeAttribute("data-ephia-target-active");
+      }
+      if (state.activeTargetId) {
+        targetManager.get(state.activeTargetId)?.element?.setAttribute("data-ephia-target-active", "true");
+        targetManager.setActive(state.activeTargetId);
+      }
+      prevActiveId = state.activeTargetId;
+    });
+
+    let prevSessionActive = false;
+    const unsubSession = store.subscribe((state) => {
+      const isActive = state.status !== "idle" && state.status !== "error";
+      if (isActive && !prevSessionActive) {
+        targetManager.syncActiveTarget();
+      }
+      prevSessionActive = isActive;
+      if (isActive) {
+        document.body.setAttribute("data-ephia-session-active", "true");
+      } else {
+        document.body.removeAttribute("data-ephia-session-active");
+      }
+    });
+
+    return () => {
+      preloadAbort.abort();
+      unsubPageHide();
+      unsubTransport();
+      unsubStore();
+      unsubActive();
+      unsubSession();
+      unsubServerEvent();
+      applyServerEventRef.current = () => {};
+      targetManager.dispose();
+      targetManagerRef.current = null;
+      document.body.removeAttribute("data-ephia-session-active");
+      warmupEvents.forEach((evt) =>
+        document.removeEventListener(evt, triggerWarmup)
+      );
+      client.releasePreloadedSession();
+      client.dispose().catch(() => {});
+      clientRef.current = null;
+      setClientEpoch((epoch) => epoch + 1);
+    };
+  }, [resolvedApiUrl, apiKey, bearerToken, clientType, transport, sessionOptionsKey, preloadSession, preloadInitialTargetId, noiseFilter, vadGate]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    clientRef.current?.setPreferredAudioInputDeviceId(audioInputDeviceId);
+  }, [audioInputDeviceId]);
+
+  const config: EphiaProviderConfig = useMemo(() => {
+    return {
+      apiUrl: resolvedApiUrl,
+      apiKey,
+      language: options.language ?? "fr",
+      medicalDomain: options.medicalDomain,
+    };
+  }, [
+    resolvedApiUrl,
+    apiKey,
+    options.language,
+    options.medicalDomain,
+  ]);
+
+  const registerTarget = useRef(
+    (id: string, binding: import("../../core/bindings/EphiaBinding").EphiaBinding, opts?: { mode?: string; element?: HTMLElement }) => {
+      const tm = targetManagerRef.current;
+      if (!tm) return () => {};
+      binding.attach();
+      const token = tm.register({ id, binding, mode: opts?.mode ?? "write", element: opts?.element });
+      return () => {
+        const removed = tm.unregister(id, token);
+        if (removed) binding.detach();
+      };
+    }
+  );
+
+  const applyServerEvent = useRef((event: EphiaServerEvent) => {
+    applyServerEventRef.current(event);
+  });
+
+  const publicCtxValue = useMemo(
+    () => ({
+      store,
+      registerTarget: registerTarget.current,
+      applyServerEvent: applyServerEvent.current,
+      config,
+    }),
+    [store, config]
+  );
+
+  const internalCtxValue = useMemo<EphiaInternalContextValue>(
+    () => ({ store, clientRef, targetManagerRef, clientEpoch }),
+    [store, clientEpoch]
+  );
+
+  return (
+    <EphiaInternalContext.Provider value={internalCtxValue}>
+      <EphiaContext.Provider value={publicCtxValue}>{children}</EphiaContext.Provider>
+    </EphiaInternalContext.Provider>
+  );
+}

package/src/react/registry/binding-factory.ts

@@ -0,0 +1,7 @@
+export type {
+  TargetOptions,
+  TargetMode,
+  TargetInsertionMode,
+  TargetDescriptor,
+} from "../../core/bindings/binding-factory";
+export { createBindingForElement } from "../../core/bindings/binding-factory";

package/src/react/registry/detect-editor-type.ts

@@ -0,0 +1,2 @@
+export type { EditorType } from "../../core/bindings/detect-editor-type";
+export { detectEditorType } from "../../core/bindings/detect-editor-type";

package/src/react/registry/events.ts

@@ -0,0 +1,37 @@
+export const EPHIA_TARGET_FOCUSED = "ephia:target:focused";
+export const EPHIA_TIPTAP_MOUNTED = "ephia:tiptap:mounted";
+export const EPHIA_TIPTAP_DESTROYED = "ephia:tiptap:destroyed";
+export const EPHIA_CODEMIRROR_MOUNTED = "ephia:codemirror:mounted";
+export const EPHIA_CODEMIRROR_DESTROYED = "ephia:codemirror:destroyed";
+export const EPHIA_MONACO_MOUNTED = "ephia:monaco:mounted";
+export const EPHIA_MONACO_DESTROYED = "ephia:monaco:destroyed";
+
+export interface EphiaTargetFocusedDetail { id: string }
+export interface EphiaEditorMountedDetail { el: HTMLElement }
+
+declare global {
+  interface DocumentEventMap {
+    [EPHIA_TARGET_FOCUSED]: CustomEvent<EphiaTargetFocusedDetail>;
+    [EPHIA_TIPTAP_MOUNTED]: CustomEvent<EphiaEditorMountedDetail>;
+    [EPHIA_TIPTAP_DESTROYED]: CustomEvent<EphiaEditorMountedDetail>;
+    [EPHIA_CODEMIRROR_MOUNTED]: CustomEvent<EphiaEditorMountedDetail>;
+    [EPHIA_CODEMIRROR_DESTROYED]: CustomEvent<EphiaEditorMountedDetail>;
+    [EPHIA_MONACO_MOUNTED]: CustomEvent<EphiaEditorMountedDetail>;
+    [EPHIA_MONACO_DESTROYED]: CustomEvent<EphiaEditorMountedDetail>;
+  }
+}
+
+function dispatchEditorEvent(type: string, el: HTMLElement): void {
+  document.dispatchEvent(new CustomEvent(type, { detail: { el } }));
+}
+
+export function dispatchTargetFocused(id: string): void {
+  document.dispatchEvent(new CustomEvent(EPHIA_TARGET_FOCUSED, { detail: { id } }));
+}
+
+export function dispatchTiptapMounted(el: HTMLElement): void { dispatchEditorEvent(EPHIA_TIPTAP_MOUNTED, el); }
+export function dispatchTiptapDestroyed(el: HTMLElement): void { dispatchEditorEvent(EPHIA_TIPTAP_DESTROYED, el); }
+export function dispatchCodeMirrorMounted(el: HTMLElement): void { dispatchEditorEvent(EPHIA_CODEMIRROR_MOUNTED, el); }
+export function dispatchCodeMirrorDestroyed(el: HTMLElement): void { dispatchEditorEvent(EPHIA_CODEMIRROR_DESTROYED, el); }
+export function dispatchMonacoMounted(el: HTMLElement): void { dispatchEditorEvent(EPHIA_MONACO_MOUNTED, el); }
+export function dispatchMonacoDestroyed(el: HTMLElement): void { dispatchEditorEvent(EPHIA_MONACO_DESTROYED, el); }

package/src/react/registry/registries/CodeMirrorInstanceRegistry.ts

@@ -0,0 +1,24 @@
+import { dispatchCodeMirrorMounted, dispatchCodeMirrorDestroyed } from "../events";
+import type { CMEditorView } from "../../../shared/types/editors";
+
+const registry = new WeakMap<HTMLElement, CMEditorView>();
+
+export const CodeMirrorInstanceRegistry = {
+  set(el: HTMLElement, view: CMEditorView): void {
+    registry.set(el, view);
+    dispatchCodeMirrorMounted(el);
+  },
+
+  get(el: HTMLElement): CMEditorView | undefined {
+    if (registry.has(el)) return registry.get(el);
+    // Chercher dans les descendants (.cm-editor peut être le wrapper, .cm-content l'interne)
+    const inner = el.querySelector<HTMLElement>(".cm-editor, .cm-content");
+    if (inner) return registry.get(inner);
+    return undefined;
+  },
+
+  delete(el: HTMLElement): void {
+    registry.delete(el);
+    dispatchCodeMirrorDestroyed(el);
+  },
+};

package/src/react/registry/registries/MonacoInstanceRegistry.ts

@@ -0,0 +1,23 @@
+import { dispatchMonacoMounted, dispatchMonacoDestroyed } from "../events";
+import type { MonacoEditorInstance } from "../../../shared/types/editors";
+
+const registry = new WeakMap<HTMLElement, MonacoEditorInstance>();
+
+export const MonacoInstanceRegistry = {
+  set(el: HTMLElement, editor: MonacoEditorInstance): void {
+    registry.set(el, editor);
+    dispatchMonacoMounted(el);
+  },
+
+  get(el: HTMLElement): MonacoEditorInstance | undefined {
+    if (registry.has(el)) return registry.get(el);
+    const inner = el.querySelector<HTMLElement>(".monaco-editor");
+    if (inner) return registry.get(inner);
+    return undefined;
+  },
+
+  delete(el: HTMLElement): void {
+    registry.delete(el);
+    dispatchMonacoDestroyed(el);
+  },
+};