@ephia/dova-sdk 1.0.0

package/src/react/hooks/useEphia.ts

@@ -0,0 +1,367 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { useStore } from "zustand";
+import { useShallow } from "zustand/react/shallow";
+import { useEphiaContext, useOptionalEphiaContext } from "../provider/EphiaContext";
+import { useEphiaInternal } from "../provider/EphiaInternalContext";
+import type { EphiaError, EphiaStatus, EphiaPartial } from "../store/types";
+import type { EphiaConnectionState } from "../../core/connection/connection-state";
+import type { EphiaAudioState } from "../../shared/state/audio-state";
+import type { EphiaStartOptions, EphiaStartResult } from "../../core/client/client-options";
+import type { EphiaServerEvent, ResetReason } from "ephia-protocol";
+import { getMessage } from "../../shared/errors/messages";
+import { toEphiaError } from "../../shared/errors/EphiaSdkError";
+
+const FINALIZATION_TIMEOUT_MS = 30_000;
+
+// ─── Hook principal ───────────────────────────────────────────────────────────
+
+export interface UseEphiaReturn {
+  // État
+  status: EphiaStatus;
+  sessionId: string | null;
+  activeTargetId: string | null;
+  error: { code: string; message: string } | null;
+
+  // Booléens commodité
+  isIdle: boolean;
+  isRecording: boolean;
+  isProcessing: boolean;
+  isBusy: boolean;
+  hasError: boolean;
+
+  // Actions
+  start: (targetId?: string, options?: EphiaStartOptions) => Promise<EphiaStartResult>;
+  stop: () => Promise<void>;
+  toggle: (targetId?: string, options?: EphiaStartOptions) => Promise<void>;
+
+  pause: () => Promise<void>;
+  resume: () => Promise<void>;
+  endSession: () => Promise<void>;
+  warmupMic: () => Promise<void>;
+
+  setActiveTarget: (id: string) => void;
+  resetTarget: (id?: string, reason?: ResetReason) => Promise<void>;
+  resetSession: (reason?: ResetReason) => Promise<void>;
+  sendEditorContext: (id?: string) => Promise<void>;
+  applyServerEvent: (event: EphiaServerEvent) => void;
+}
+
+export function useEphia(): UseEphiaReturn {
+  const { store, applyServerEvent } = useEphiaContext();
+  const internal = useEphiaInternal();
+
+  const status = useStore(store, (s) => s.status);
+  const sessionId = useStore(store, (s) => s.sessionId);
+  const activeTargetId = useStore(store, (s) => s.activeTargetId);
+  const error = useStore(store, useShallow((s) => s.error));
+
+  const start = useCallback(
+    async (targetId?: string, options?: EphiaStartOptions): Promise<EphiaStartResult> => {
+      const client = internal.clientRef.current;
+      const targetManager = internal.targetManagerRef.current;
+      if (!client || !targetManager) {
+        throw new Error(getMessage("provider.not_initialized"));
+      }
+
+      const currentStatus = store.getState().status;
+      if (currentStatus !== "idle" && currentStatus !== "error") {
+        return { sessionId: store.getState().sessionId };
+      }
+
+      const clickTs = typeof window !== "undefined" ? window.__ephia_record_click_ts : undefined;
+      const startCallTs = Date.now();
+      const deltaFromClick = clickTs ? startCallTs - clickTs : undefined;
+
+      window.dispatchEvent(
+        new CustomEvent("ephia:sdk-debug", {
+          detail: {
+            type: "sdk.record.start_called",
+            sessionId: null,
+            payload: {
+              message: `start() appelé${deltaFromClick !== undefined ? ` (${deltaFromClick}ms après clic)` : ""}`,
+              deltaFromClick,
+              ts: startCallTs,
+            },
+          },
+        })
+      );
+
+      if (targetId) {
+        targetManager.setActive(targetId);
+      }
+
+      const activeTargetId = targetId ?? targetManager.getActiveTargetId() ?? undefined;
+      targetManager.prepareForDictation(activeTargetId);
+
+      store.getState()._setStatus("processing");
+
+      try {
+        const result = await client.start(
+          targetId ? { ...options, initialTargetId: targetId } : options
+        );
+        targetManager.syncActiveTarget();
+        targetManager.flushEditorContext(
+          targetId ?? targetManager.getActiveTargetId() ?? undefined
+        );
+        store.getState()._setStatus("recording");
+        store.getState()._setSessionId(result.sessionId);
+        return result;
+      } catch (err) {
+        store.getState()._setError(toEphiaError(err));
+        store.getState()._setStatus("error");
+        throw err;
+      }
+    },
+    [store, internal]
+  );
+
+  const stop = useCallback(async () => {
+    const client = internal.clientRef.current;
+    if (!client) return;
+
+    const current = store.getState().status;
+    // Permettre l'arrêt pendant le démarrage (processing) pour éviter qu'un
+    // push-to-talk très court laisse le micro ouvert (race start/stop).
+    if (current === "idle" || current === "error") return;
+
+    store.getState()._setStatus("processing");
+
+    try {
+      await client.stop();
+
+      const clientState = client.getState();
+
+      if (
+        clientState.status === "idle" ||
+        clientState.status === "paused" ||
+        clientState.status === "ended"
+      ) {
+        store.getState()._setStatus("idle");
+      } else if (store.getState().status === "processing") {
+        store.getState()._setStatus("idle");
+      }
+    } catch (err) {
+      store.getState()._setError(toEphiaError(err));
+      store.getState()._setStatus("error");
+      throw err;
+    }
+  }, [store, internal]);
+
+  const toggle = useCallback(
+    async (targetId?: string, options?: EphiaStartOptions) => {
+      const { status } = store.getState();
+      if (status === "recording") {
+        await stop();
+      } else {
+        await start(targetId, options);
+      }
+    },
+    [store, start, stop]
+  );
+
+  const pause = useCallback(async () => {
+    // V2 initial: pause is equivalent to stop (session stays alive on the backend/client).
+    await stop();
+  }, [stop]);
+
+  const resume = useCallback(
+    async (options?: EphiaStartOptions) => {
+      const client = internal.clientRef.current;
+      const targetManager = internal.targetManagerRef.current;
+      if (!client) return;
+
+      const clientStatus = client.getState().status;
+      if (clientStatus === "paused") {
+        targetManager?.prepareForDictation(
+          store.getState().activeTargetId ?? targetManager.getActiveTargetId() ?? undefined,
+        );
+        await client.start(options);
+        return;
+      }
+
+      // Fallback: if the client is not paused, start a fresh session.
+      await start(undefined, options);
+    },
+    [internal, start, store]
+  );
+
+  const endSession = useCallback(async () => {
+    const client = internal.clientRef.current;
+    if (!client) return;
+
+    const current = store.getState().status;
+    if (current !== "recording" && current !== "processing") return;
+
+    store.getState()._setStatus("processing");
+
+    const timeout = setTimeout(() => {
+      store.getState()._setStatus("error");
+      store.getState()._setError({
+        code: "client.finalization_timeout",
+        message: getMessage("client.finalization_timeout"),
+      });
+    }, FINALIZATION_TIMEOUT_MS);
+
+    try {
+      await client.endSession();
+    } catch (err) {
+      store.getState()._setError(toEphiaError(err));
+      store.getState()._setStatus("error");
+      throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    const clientState = client.getState();
+    if (clientState.status === "idle") {
+      store.getState()._setStatus("idle");
+      return;
+    }
+
+    if (clientState.status === "error" || clientState.error) {
+      if (clientState.error) {
+        store.getState()._setError(clientState.error);
+      }
+      store.getState()._setStatus("error");
+      return;
+    }
+
+    if (store.getState().status === "processing") {
+      store.getState()._setStatus("idle");
+    }
+  }, [store, internal]);
+
+  const warmupMic = useCallback(async () => {
+    const client = internal.clientRef.current;
+    if (!client) return;
+    await client.warmupMic().catch(() => {});
+  }, [internal]);
+
+  const setActiveTarget = useCallback(
+    (id: string) => {
+      const targetManager = internal.targetManagerRef.current;
+      if (!targetManager) return;
+      targetManager.setActive(id);
+    },
+    [internal]
+  );
+
+  const sendEditorContext = useCallback(
+    async (id?: string) => {
+      const targetManager = internal.targetManagerRef.current;
+      if (!targetManager) return;
+      targetManager.flushEditorContext(id);
+    },
+    [internal]
+  );
+
+  const resetTarget = useCallback(
+    async (id?: string, reason: ResetReason = "user_explicit") => {
+      const targetManager = internal.targetManagerRef.current;
+      if (!targetManager) return;
+
+      const targetId = id ?? store.getState().activeTargetId;
+      if (!targetId) return;
+
+      targetManager.reset("target", targetId, reason);
+    },
+    [store, internal]
+  );
+
+  const resetSession = useCallback(
+    async (reason: ResetReason = "user_explicit") => {
+      const targetManager = internal.targetManagerRef.current;
+      if (!targetManager) return;
+      targetManager.reset("global", undefined, reason);
+    },
+    [internal]
+  );
+
+  return {
+    status,
+    sessionId,
+    activeTargetId,
+    error,
+    isIdle: status === "idle",
+    isRecording: status === "recording",
+    isProcessing: status === "processing",
+    isBusy: status !== "idle" && status !== "error",
+    hasError: status === "error",
+    start,
+    stop,
+    toggle,
+    pause,
+    resume,
+    endSession,
+    warmupMic,
+    setActiveTarget,
+    resetTarget,
+    resetSession,
+    sendEditorContext,
+    applyServerEvent,
+  };
+}
+
+// ─── Hooks sélecteurs légers (anti re-render) ─────────────────────────────────
+
+/** Re-rend uniquement sur changement de status. */
+export function useEphiaStatus(): EphiaStatus {
+  const { store } = useEphiaContext();
+  return useStore(store, (s) => s.status);
+}
+
+/** Comme useEphiaStatus mais retourne undefined en dehors d'un EphiaProvider. */
+export function useOptionalEphiaStatus(): EphiaStatus | undefined {
+  const ctx = useOptionalEphiaContext();
+  return useSyncExternalStore(
+    (callback) => {
+      if (!ctx) return () => {};
+      return ctx.store.subscribe(callback);
+    },
+    () => (ctx ? ctx.store.getState().status : undefined),
+    () => undefined,
+  );
+}
+
+/** Re-rend uniquement sur changement d'erreur session (ex. session.error STT). */
+export function useEphiaError(): EphiaError | null {
+  const { store } = useEphiaContext();
+  return useStore(store, (s) => s.error);
+}
+
+/** Re-rend sur chaque partial — à utiliser uniquement dans les composants d'affichage. */
+export function useEphiaPartial(): EphiaPartial | null {
+  const { store } = useEphiaContext();
+  return useStore(store, useShallow((s) => s.partial));
+}
+
+/** Re-rend sur changement de connexion. */
+export function useEphiaConnection(): EphiaConnectionState {
+  const { store } = useEphiaContext();
+  return useStore(store, useShallow((s) => s.connection));
+}
+
+/** Comme useEphiaConnection mais retourne undefined en dehors d'un EphiaProvider. */
+export function useOptionalEphiaConnection(): EphiaConnectionState | undefined {
+  const ctx = useOptionalEphiaContext();
+  return useSyncExternalStore(
+    (callback) => {
+      if (!ctx) return () => {};
+      return ctx.store.subscribe(callback);
+    },
+    () => (ctx ? ctx.store.getState().connection : undefined),
+    () => undefined,
+  );
+}
+
+/** Re-rend sur changement de niveau audio. */
+export function useEphiaAudioLevel(): EphiaAudioState {
+  const { store } = useEphiaContext();
+  return useStore(store, useShallow((s) => s.audio));
+}
+
+/** Re-rend uniquement sur changement d'état parole (VAD gate). */
+export function useEphiaSpeaking(): boolean {
+  const { store } = useEphiaContext();
+  return useStore(store, (s) => s.audio.speaking);
+}

package/src/react/hooks/useEphiaDiscardTarget.ts

@@ -0,0 +1,53 @@
+import { useEffect, useMemo } from "react";
+import type { EditorContext } from "ephia-protocol";
+import type { EphiaBinding } from "../../core/bindings/EphiaBinding";
+import { useEphiaContext } from "../provider/EphiaContext";
+
+function createDiscardBinding(): EphiaBinding {
+  return {
+    kind: "discard",
+    attach() {},
+    detach() {},
+    getText() {
+      return "";
+    },
+    getEditorContext(targetId = ""): EditorContext {
+      return {
+        targetId,
+        documentEmpty: true,
+        insertionMode: "insert_at_cursor",
+        leftContext: "",
+        rightContext: "",
+        selectedText: null,
+        cursorOffset: 0,
+      };
+    },
+    previewSegment() {},
+    upsertSegment() {},
+    removeSegment() {},
+    removeSegments() {},
+  };
+}
+
+export interface UseEphiaDiscardTargetOptions {
+  enabled?: boolean;
+}
+
+/**
+ * Enregistre une cible no-op (segments ignorés côté éditeur).
+ * Utile en mode « event-only » : l'app affiche le transcript via useEphiaServerEvent
+ * sans textarea/TipTap, mais le backend route quand même vers un targetId.
+ */
+export function useEphiaDiscardTarget(
+  id: string,
+  options: UseEphiaDiscardTargetOptions = {},
+): void {
+  const { registerTarget } = useEphiaContext();
+  const { enabled = true } = options;
+  const binding = useMemo(() => createDiscardBinding(), []);
+
+  useEffect(() => {
+    if (!enabled) return;
+    return registerTarget(id, binding, { mode: "write" });
+  }, [binding, enabled, id, registerTarget]);
+}

package/src/react/hooks/useEphiaServerEvent.ts

@@ -0,0 +1,33 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import type { EphiaServerEvent } from "ephia-protocol";
+import { useEphiaInternal } from "../provider/EphiaInternalContext";
+
+/**
+ * Subscribe to a specific server event emitted by the underlying SDK client.
+ *
+ * @example
+ *   useEphiaServerEvent("segment.operation", (event) => {
+ *     console.log("segment", event.payload.segmentId, event.payload.text);
+ *   });
+ */
+export function useEphiaServerEvent<T extends EphiaServerEvent["type"]>(
+  type: T,
+  handler: (event: Extract<EphiaServerEvent, { type: T }>) => void
+): void {
+  const { clientRef, clientEpoch } = useEphiaInternal();
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const client = clientRef.current;
+    if (!client) return;
+
+    return client.onServerEvent((event) => {
+      if (event.type === type) {
+        handlerRef.current(event as Extract<EphiaServerEvent, { type: T }>);
+      }
+    });
+  }, [clientRef, clientEpoch, type]);
+}

package/src/react/hooks/useEphiaTarget.ts

@@ -0,0 +1,47 @@
+import { useEffect } from "react";
+import { useEphiaContext } from "../provider/EphiaContext";
+import { useEphiaInternal } from "../provider/EphiaInternalContext";
+import { NativeBinding } from "../../core/bindings/native/NativeBinding";
+
+export interface UseEphiaNativeTargetOptions {
+  id: string;
+  mode?: string;
+  label?: string;
+  enabled?: boolean;
+}
+
+/** @deprecated Use `UseEphiaNativeTargetOptions` instead. */
+export type UseEphiaTargetOptions = UseEphiaNativeTargetOptions;
+
+/**
+ * Registers a textarea or input element as a V2 Ephia target.
+ * Creates a NativeBinding and wires it to the TargetManager via context.
+ *
+ * @example
+ * const ref = useRef<HTMLTextAreaElement>(null)
+ * useEphiaNativeTarget(ref, { id: 'report', label: 'Compte rendu' })
+ * return <textarea ref={ref} />
+ */
+export function useEphiaNativeTarget<T extends HTMLInputElement | HTMLTextAreaElement>(
+  ref: React.RefObject<T | null>,
+  options: UseEphiaNativeTargetOptions,
+): void {
+  const { registerTarget } = useEphiaContext();
+  const { clientEpoch } = useEphiaInternal();
+  const { id, mode, enabled } = options;
+
+  useEffect(() => {
+    if (enabled === false) return;
+    const el = ref.current;
+    if (!el) return;
+    return registerTarget(id, new NativeBinding(el), {
+      mode: mode ?? "write",
+      element: el,
+    });
+  }, [ref, id, mode, enabled, registerTarget, clientEpoch]);
+}
+
+/**
+ * @deprecated Use `useEphiaNativeTarget` for textarea/input fields.
+ */
+export const useEphiaTarget = useEphiaNativeTarget;

package/src/react/hooks/useEphiaTranscript.ts

@@ -0,0 +1,22 @@
+import { useEffect, useReducer } from "react";
+import { liveTranscriptReducer } from "../../core/transcript/transcript.reducer";
+import type { LiveTranscriptAction } from "../../core/transcript/transcript.reducer";
+import { initialLiveTranscriptState } from "../../core/transcript/transcript.state";
+import type { LiveTranscriptState } from "../../core/transcript/transcript.state";
+
+export function useEphiaTranscript(): {
+  state: LiveTranscriptState;
+  dispatch: (action: LiveTranscriptAction) => void;
+} {
+  const [state, dispatch] = useReducer(liveTranscriptReducer, initialLiveTranscriptState);
+
+  useEffect(() => {
+    if (state.diagnostics.processingChunks === 0) return;
+    const id = setInterval(() => {
+      dispatch({ type: "tick" });
+    }, 200);
+    return () => clearInterval(id);
+  }, [dispatch, state.diagnostics.processingChunks]);
+
+  return { state, dispatch };
+}

package/src/react/index.ts

@@ -0,0 +1,58 @@
+// Provider & Context
+export { EphiaProvider } from "./provider/EphiaProvider";
+export { EphiaAuto } from "./EphiaAuto";
+export type { EphiaProviderProps } from "./provider/EphiaProvider";
+
+// Hooks
+export {
+  useEphia,
+  useEphiaStatus,
+  useOptionalEphiaStatus,
+  useEphiaError,
+  useEphiaPartial,
+  useEphiaConnection,
+  useOptionalEphiaConnection,
+  useEphiaAudioLevel,
+  useEphiaSpeaking,
+} from "./hooks/useEphia";
+export type { UseEphiaReturn } from "./hooks/useEphia";
+export type { EphiaStartResult } from "../core/client/client-options";
+export {
+  useEphiaNativeTarget,
+  useEphiaTarget,
+} from "./hooks/useEphiaTarget";
+export type {
+  UseEphiaNativeTargetOptions,
+  UseEphiaTargetOptions,
+} from "./hooks/useEphiaTarget";
+export { useEphiaTiptap } from "./hooks/targets/useEphiaTiptap";
+export { useEphiaServerEvent } from "./hooks/useEphiaServerEvent";
+export {
+  useEphiaDiscardTarget,
+} from "./hooks/useEphiaDiscardTarget";
+export type { UseEphiaDiscardTargetOptions } from "./hooks/useEphiaDiscardTarget";
+export { EphiaV2PreviewMark, EphiaV2CommittedMark } from "../core/bindings/tiptap/TiptapBinding";
+export {
+  EphiaSpeechMikeProvider,
+  useEphiaSpeechMike,
+} from "../devices/speechmike";
+export type {
+  EphiaSpeechMikeAction,
+  EphiaSpeechMikeAudioStatus,
+  EphiaSpeechMikeButton,
+  EphiaSpeechMikeDeviceInfo,
+  EphiaSpeechMikeError,
+  EphiaSpeechMikeHidStatus,
+  EphiaSpeechMikeLedIntent,
+  EphiaSpeechMikeProviderProps,
+  EphiaSpeechMikeState,
+  EphiaSpeechMikeStatus,
+} from "../devices/speechmike";
+
+// Components
+export { EphiaDictationButton } from "./components/EphiaDictationButton";
+export { EphiaStatusBar } from "./components/EphiaStatusBar";
+export { EphiaTextarea } from "./components/EphiaTextarea";
+
+// Store
+export type { EphiaStatus } from "./store/types";

package/src/react/provider/EphiaContext.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { EphiaServerEvent } from "ephia-protocol";
+import type { EphiaStore } from "../store/create-ephia-store";
+import type { EphiaBinding } from "../../core/bindings/EphiaBinding";
+
+export interface EphiaProviderConfig {
+  apiUrl?: string;
+  apiKey?: string;
+  bearerToken?: string;
+  clientType?: string;
+  language?: string;
+  medicalDomain?: string;
+}
+
+export interface RegisterTargetOptions {
+  mode?: string;
+  element?: HTMLElement;
+}
+
+/**
+ * Public context value exposed by <EphiaProvider>.
+ *
+ * V2 rules:
+ *  - no direct client access (getClient / clientRef removed)
+ *  - no legacy registry (registryRef removed)
+ *  - no voice-formatting config (handled backend-side)
+ *
+ * Consumers receive the reactive store and a target registration helper.
+ */
+export interface EphiaContextValue {
+  store: EphiaStore;
+  /**
+   * Registers a V2 EphiaBinding with the TargetManager.
+   * Returns a cleanup function that unregisters and detaches the binding.
+   */
+  registerTarget: (id: string, binding: EphiaBinding, opts?: RegisterTargetOptions) => () => void;
+  /**
+   * Réapplique un événement serveur (replay backend / événements manqués).
+   * Délègue au TranscriptApplier interne du provider.
+   */
+  applyServerEvent: (event: EphiaServerEvent) => void;
+  config: EphiaProviderConfig;
+}
+
+export const EphiaContext = createContext<EphiaContextValue | null>(null);
+
+export function useEphiaContext(): EphiaContextValue {
+  const ctx = useContext(EphiaContext);
+  if (!ctx) {
+    throw new Error(
+      "[ephia-audio] useEphia() doit être utilisé dans un <EphiaProvider>. " +
+        "Vérifiez que <EphiaProvider> est bien dans votre layout racine."
+    );
+  }
+  return ctx;
+}
+
+/** Returns the context value without throwing — null when outside a Provider. */
+export function useOptionalEphiaContext(): EphiaContextValue | null {
+  return useContext(EphiaContext);
+}

package/src/react/provider/EphiaInternalContext.ts

@@ -0,0 +1,32 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { EphiaStore } from "../store/create-ephia-store";
+import type { EphiaAudioClient } from "../../core/client/EphiaAudioClient";
+import type { TargetManager } from "../../core/targets/TargetManager";
+
+/**
+ * Internal context used by SDK hooks that need direct access to the audio client
+ * and target manager. This context is intentionally NOT exported from the public
+ * package API so that consumers cannot bypass the V2 orchestration layer.
+ */
+export interface EphiaInternalContextValue {
+  store: EphiaStore;
+  clientRef: React.MutableRefObject<EphiaAudioClient | null>;
+  targetManagerRef: React.MutableRefObject<TargetManager | null>;
+  /** Incrémenté à chaque (re)création du client audio — pour ré-abonner les hooks tardifs. */
+  clientEpoch: number;
+}
+
+export const EphiaInternalContext = createContext<EphiaInternalContextValue | null>(null);
+
+export function useEphiaInternal(): EphiaInternalContextValue {
+  const ctx = useContext(EphiaInternalContext);
+  if (!ctx) {
+    throw new Error(
+      "[ephia-audio] useEphiaInternal() doit être utilisé dans un <EphiaProvider>. " +
+        "Vérifiez que <EphiaProvider> est bien dans votre layout racine."
+    );
+  }
+  return ctx;
+}