@ephia/dova-sdk 1.0.0

package/src/rich-editor/use-ephia-rich-editor.test.tsx

@@ -0,0 +1,202 @@
+// @vitest-environment jsdom
+
+import React, { createContext } from "react";
+import { describe, expect, it, vi, afterEach } from "vitest";
+import { cleanup, render } from "@testing-library/react";
+import { EphiaContext } from "../react/provider/EphiaContext";
+import type { EphiaContextValue } from "../react/provider/EphiaContext";
+import type { EphiaRichEditorAdapter } from "./types";
+import { useEphiaRichEditor } from "./use-ephia-rich-editor";
+
+afterEach(cleanup);
+
+function makeAdapter(identity: object): EphiaRichEditorAdapter {
+  return {
+    kind: "test",
+    identity,
+    createBinding: () => ({
+      kind: "test",
+      attach: vi.fn(),
+      detach: vi.fn(),
+      getText: () => "",
+      getEditorContext: () => ({
+        targetId: "",
+        documentEmpty: true,
+        insertionMode: "append" as const,
+        leftContext: "",
+        rightContext: "",
+        selectedText: null,
+        cursorOffset: 0,
+      }),
+      upsertSegment: vi.fn(),
+      removeSegment: vi.fn(),
+      removeSegments: vi.fn(),
+    }),
+  };
+}
+
+function makeContext(registerTarget: EphiaContextValue["registerTarget"]): EphiaContextValue {
+  return {
+    store: {} as any,
+    config: {},
+    registerTarget,
+    applyServerEvent: vi.fn(),
+  };
+}
+
+function Wrapper({
+  ctx,
+  children,
+}: {
+  ctx: EphiaContextValue;
+  children: React.ReactNode;
+}) {
+  return (
+    <EphiaContext.Provider value={ctx}>{children}</EphiaContext.Provider>
+  );
+}
+
+describe("useEphiaRichEditor", () => {
+  it("calls registerTarget once on mount", () => {
+    const unregister = vi.fn();
+    const registerTarget = vi.fn(() => unregister);
+    const ctx = makeContext(registerTarget);
+    const identity = {};
+    const adapter = makeAdapter(identity);
+
+    function Test() {
+      useEphiaRichEditor(adapter, { id: "report", label: "Report" });
+      return null;
+    }
+
+    render(
+      <Wrapper ctx={ctx}>
+        <Test />
+      </Wrapper>,
+    );
+
+    expect(registerTarget).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not re-register when adapter object is recreated with same identity", () => {
+    const unregister = vi.fn();
+    const registerTarget = vi.fn(() => unregister);
+    const ctx = makeContext(registerTarget);
+    const identity = {};
+
+    function Test() {
+      // Simulate inline creation: new adapter object each render, same identity
+      const adapter = makeAdapter(identity);
+      useEphiaRichEditor(adapter, { id: "report", label: "Report" });
+      return null;
+    }
+
+    const { rerender } = render(
+      <Wrapper ctx={ctx}>
+        <Test />
+      </Wrapper>,
+    );
+    rerender(
+      <Wrapper ctx={ctx}>
+        <Test />
+      </Wrapper>,
+    );
+    rerender(
+      <Wrapper ctx={ctx}>
+        <Test />
+      </Wrapper>,
+    );
+
+    expect(registerTarget).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-registers when identity changes", () => {
+    const unregister = vi.fn();
+    const registerTarget = vi.fn(() => unregister);
+    const ctx = makeContext(registerTarget);
+
+    const identityA = {};
+    const identityB = {};
+
+    function Test({ which }: { which: "a" | "b" }) {
+      const identity = which === "a" ? identityA : identityB;
+      useEphiaRichEditor(makeAdapter(identity), { id: "report" });
+      return null;
+    }
+
+    const { rerender } = render(
+      <Wrapper ctx={ctx}>
+        <Test which="a" />
+      </Wrapper>,
+    );
+
+    expect(registerTarget).toHaveBeenCalledTimes(1);
+
+    rerender(
+      <Wrapper ctx={ctx}>
+        <Test which="b" />
+      </Wrapper>,
+    );
+
+    expect(registerTarget).toHaveBeenCalledTimes(2);
+  });
+
+  it("calls cleanup (unregister) on unmount", () => {
+    const unregister = vi.fn();
+    const registerTarget = vi.fn(() => unregister);
+    const ctx = makeContext(registerTarget);
+    const adapter = makeAdapter({});
+
+    function Test() {
+      useEphiaRichEditor(adapter, { id: "report" });
+      return null;
+    }
+
+    const { unmount } = render(
+      <Wrapper ctx={ctx}>
+        <Test />
+      </Wrapper>,
+    );
+
+    expect(unregister).not.toHaveBeenCalled();
+    unmount();
+    expect(unregister).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not register when enabled is false", () => {
+    const registerTarget = vi.fn(() => vi.fn());
+    const ctx = makeContext(registerTarget);
+    const adapter = makeAdapter({});
+
+    function Test() {
+      useEphiaRichEditor(adapter, { id: "report", enabled: false });
+      return null;
+    }
+
+    render(
+      <Wrapper ctx={ctx}>
+        <Test />
+      </Wrapper>,
+    );
+
+    expect(registerTarget).not.toHaveBeenCalled();
+  });
+
+  it("does not register when adapter is null", () => {
+    const registerTarget = vi.fn(() => vi.fn());
+    const ctx = makeContext(registerTarget);
+
+    function Test() {
+      useEphiaRichEditor(null, { id: "report" });
+      return null;
+    }
+
+    render(
+      <Wrapper ctx={ctx}>
+        <Test />
+      </Wrapper>,
+    );
+
+    expect(registerTarget).not.toHaveBeenCalled();
+  });
+});

package/src/rich-editor/use-ephia-rich-editor.ts

@@ -0,0 +1,47 @@
+import { useEffect, useRef } from "react";
+import { useEphiaContext } from "../react/provider/EphiaContext";
+import { useEphiaInternal } from "../react/provider/EphiaInternalContext";
+import type { EphiaRichEditorAdapter, UseEphiaRichEditorOptions } from "./types";
+
+/**
+ * Registers a rich text editor via an adapter as a V2 Ephia target.
+ *
+ * @example
+ * const ephiaRef = useEphiaRichEditor(
+ *   createTiptapEphiaAdapter(editor),
+ *   { id: "report", label: "Compte rendu" },
+ * );
+ *
+ * return (
+ *   <div ref={ephiaRef}>
+ *     <EditorContent editor={editor} />
+ *   </div>
+ * );
+ */
+export function useEphiaRichEditor(
+  adapter: EphiaRichEditorAdapter | null,
+  options: UseEphiaRichEditorOptions,
+): React.RefObject<HTMLDivElement | null> {
+  const ref = useRef<HTMLDivElement>(null);
+  const { registerTarget } = useEphiaContext();
+  const { clientEpoch } = useEphiaInternal();
+  const { id, mode, label, enabled } = options;
+
+  const adapterKind = adapter?.kind ?? null;
+  // Use identity if provided (stable per editor instance). Fall back to the
+  // adapter object itself so custom adapters without identity still work.
+  const adapterIdentity = adapter?.identity ?? adapter ?? null;
+
+  useEffect(() => {
+    if (enabled === false) return;
+    if (!adapter) return;
+
+    const binding = adapter.createBinding({ targetId: id, label });
+    return registerTarget(id, binding, {
+      mode: mode ?? "write",
+      element: adapter.getElement?.() ?? ref.current ?? undefined,
+    });
+  }, [adapterKind, adapterIdentity, enabled, id, label, mode, registerTarget, clientEpoch]);
+
+  return ref;
+}

package/src/shared/config/endpoint.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  DEFAULT_EPHIA_SDK_API_URL,
+  resolveEphiaSdkApiUrl,
+} from "./endpoint";
+
+describe("resolveEphiaSdkApiUrl", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("uses explicit apiUrl when provided", () => {
+    expect(resolveEphiaSdkApiUrl("http://localhost:8000")).toBe(
+      "http://localhost:8000"
+    );
+  });
+
+  it("normalizes trailing slashes and /api/v* suffix on explicit url", () => {
+    expect(resolveEphiaSdkApiUrl("https://api.test/api/v1/")).toBe(
+      "https://api.test"
+    );
+  });
+
+  it("falls back to EPHIA_SDK_ENDPOINT when no explicit url", () => {
+    vi.stubEnv("EPHIA_SDK_ENDPOINT", "https://api.ephiak.app");
+    expect(resolveEphiaSdkApiUrl()).toBe("https://api.ephiak.app");
+  });
+
+  it("falls back to NEXT_PUBLIC_EPHIA_SDK_ENDPOINT when EPHIA_SDK_ENDPOINT is absent", () => {
+    vi.stubEnv("NEXT_PUBLIC_EPHIA_SDK_ENDPOINT", "https://preview.test");
+    expect(resolveEphiaSdkApiUrl()).toBe("https://preview.test");
+  });
+
+  it("prefers explicit apiUrl over env", () => {
+    vi.stubEnv("EPHIA_SDK_ENDPOINT", "https://api.ephiak.app");
+    expect(resolveEphiaSdkApiUrl("http://localhost:8000")).toBe(
+      "http://localhost:8000"
+    );
+  });
+
+  it("defaults to production api.ephia.app", () => {
+    expect(resolveEphiaSdkApiUrl()).toBe(DEFAULT_EPHIA_SDK_API_URL);
+    expect(DEFAULT_EPHIA_SDK_API_URL).toBe("https://api.ephia.app");
+  });
+});

package/src/shared/config/endpoint.ts

@@ -0,0 +1,39 @@
+/** URL API Ephia par défaut (production). */
+export const DEFAULT_EPHIA_SDK_API_URL = "https://api.ephia.app";
+
+function normalizeApiUrl(raw: string): string {
+  return raw.trim().replace(/\/+$/, "").replace(/\/api\/v\d+$/, "");
+}
+
+function readEnvEndpoint(): string | undefined {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const env = (typeof globalThis !== "undefined" && (globalThis as any).process?.env) as Record<string, string | undefined> | undefined;
+  if (!env) return undefined;
+
+  const fromEnv = env["EPHIA_SDK_ENDPOINT"]?.trim();
+  if (fromEnv) return fromEnv;
+
+  // Next.js n'expose côté client que les variables NEXT_PUBLIC_*.
+  const fromNextPublic = env["NEXT_PUBLIC_EPHIA_SDK_ENDPOINT"]?.trim();
+  if (fromNextPublic) return fromNextPublic;
+
+  return undefined;
+}
+
+/**
+ * Résout l'URL API utilisée par le SDK.
+ *
+ * Priorité :
+ * 1. `apiUrl` explicite (ex. localhost en dev)
+ * 2. `EPHIA_SDK_ENDPOINT` ou `NEXT_PUBLIC_EPHIA_SDK_ENDPOINT`
+ * 3. {@link DEFAULT_EPHIA_SDK_API_URL}
+ */
+export function resolveEphiaSdkApiUrl(explicitApiUrl?: string | null): string {
+  const explicit = explicitApiUrl?.trim();
+  if (explicit) return normalizeApiUrl(explicit);
+
+  const fromEnv = readEnvEndpoint();
+  if (fromEnv) return normalizeApiUrl(fromEnv);
+
+  return DEFAULT_EPHIA_SDK_API_URL;
+}

package/src/shared/config/schema.ts

@@ -0,0 +1,32 @@
+/**
+ * Schéma Zod de validation de la configuration du SDK.
+ * SSR-safe : pas de z.instanceof(Element) qui plante en Node/SSR.
+ */
+
+import { z } from "zod";
+
+const elementSchema = z.custom<Element>(
+  (value) =>
+    typeof Element !== "undefined" && value instanceof Element,
+  { message: "Expected DOM Element" }
+);
+
+export const ephiaSessionOptionsSchema = z.object({
+  language: z.enum(["fr", "en"]).optional(),
+  mode: z.enum(["fast_xs", "fast_s", "smart_xs", "smart_s"]).optional(),
+  debugChunks: z.boolean().optional(),
+});
+
+export const ephiaClientConfigSchema = z.object({
+  apiUrl: z.string().url(),
+  apiKey: z.string().optional(),
+  bearerToken: z.string().optional(),
+  clientType: z.string().optional(),
+  session: ephiaSessionOptionsSchema.optional(),
+  debug: z.boolean().optional(),
+  noiseFilter: z.boolean().optional(),
+  target: z.union([z.string(), elementSchema, z.null()]).optional(),
+});
+
+export type EphiaClientConfig = z.infer<typeof ephiaClientConfigSchema>;
+export type EphiaSessionOptionsConfig = z.infer<typeof ephiaSessionOptionsSchema>;

package/src/shared/effective-text.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns the text to apply to DOM/state after a finalized or committed
+ * transcript event. An empty delta is intentional and must not fall back to
+ * the raw provider text.
+ */
+export function pickEffectiveText(payload: {
+  text: string;
+  delta?: string | null;
+}): string {
+  return payload.delta !== undefined && payload.delta !== null
+    ? payload.delta
+    : payload.text;
+}

package/src/shared/errors/EphiaSdkError.ts

@@ -0,0 +1,54 @@
+/**
+ * Erreurs typées du SDK Ephia.
+ */
+
+export type EphiaSdkErrorCode =
+  | "config.invalid"
+  | "session.create_failed"
+  | "session.token_missing"
+  | "transport.connect_failed"
+  | "transport.reconnecting"
+  | "transport.disconnected"
+  | "transport.not_connected"
+  | "audio.permission_denied"
+  | "audio.no_input_device"
+  | "audio.device_in_use"
+  | "audio.track_publish_failed"
+  | "audio.silence_detected"
+  | "protocol.invalid_event"
+  | "protocol.seq_gap"
+  | "protocol.seq_gap_sync_failed"
+  | "client.invalid_state"
+  | "client.start_failed"
+  | "client.finalization_timeout"
+  | "binding.target_not_found"
+  | "binding.unsupported_editor";
+
+export class EphiaSdkError extends Error {
+  constructor(
+    public code: EphiaSdkErrorCode,
+    message: string,
+    public details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = "EphiaSdkError";
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
+}
+
+export function toEphiaError(error: unknown): { code: string; message: string } {
+  if (error instanceof EphiaSdkError) {
+    return { code: error.code, message: error.message };
+  }
+  if (error instanceof Error) {
+    return { code: "client.start_failed", message: error.message };
+  }
+  return { code: "client.start_failed", message: String(error) };
+}

package/src/shared/errors/messages.ts

@@ -0,0 +1,40 @@
+export type EphiaLang = "fr" | "en";
+
+const MESSAGES: Record<string, Record<EphiaLang, string>> = {
+  "client.start_failed": {
+    fr: "Échec du démarrage",
+    en: "Start failed",
+  },
+  "client.finalization_timeout": {
+    fr: "Timeout pendant la finalisation",
+    en: "Finalization timeout",
+  },
+  "client.stop_failed": {
+    fr: "Échec de l'arrêt",
+    en: "Stop failed",
+  },
+  "audio.no_input_device": {
+    fr: "getUserMedia n'est pas disponible dans ce contexte",
+    en: "getUserMedia is not available in this browser/context",
+  },
+  "session.create_failed": {
+    fr: "Échec de création de session",
+    en: "Failed to create session",
+  },
+  "protocol.invalid_event": {
+    fr: "Événement invalide du serveur",
+    en: "Invalid event from server",
+  },
+  "provider.not_initialized": {
+    fr: "Provider non initialisé",
+    en: "Provider not initialized",
+  },
+  "transport.disconnect_timeout": {
+    fr: "Déconnexion trop lente, abandon",
+    en: "Disconnect too slow, giving up",
+  },
+};
+
+export function getMessage(code: string, lang: EphiaLang = "fr"): string {
+  return MESSAGES[code]?.[lang] ?? code;
+}

package/src/shared/index.ts

@@ -0,0 +1,27 @@
+// Errors
+export { EphiaSdkError } from "./errors/EphiaSdkError";
+export type { EphiaSdkErrorCode } from "./errors/EphiaSdkError";
+export { getMessage } from "./errors/messages";
+export type { EphiaLang } from "./errors/messages";
+
+// Config / Schema
+export {
+  DEFAULT_EPHIA_SDK_API_URL,
+  resolveEphiaSdkApiUrl,
+} from "./config/endpoint";
+export {
+  ephiaClientConfigSchema,
+  ephiaSessionOptionsSchema,
+} from "./config/schema";
+export type {
+  EphiaClientConfig,
+  EphiaSessionOptionsConfig,
+} from "./config/schema";
+
+// Types
+export type { Mode, EphiaSessionOptions } from "./types/session";
+export { pickEffectiveText } from "./effective-text";
+
+// State
+export type { EphiaAudioPermission, EphiaAudioState } from "./state/audio-state";
+export { initialAudioState } from "./state/audio-state";

package/src/shared/state/audio-state.ts

@@ -0,0 +1,45 @@
+/**
+ * État audio local (micro, niveau, silence, permission).
+ */
+
+export type EphiaAudioPermission = "unknown" | "prompt" | "granted" | "denied";
+
+export type EphiaAudioState = {
+  permission: EphiaAudioPermission;
+
+  inputDeviceId?: string;
+  inputDeviceLabel?: string;
+  hasInputDevice: boolean;
+
+  level: number; // 0..1
+  rms: number;
+  peak: number;
+
+  isSilent: boolean;
+  silenceDurationMs: number;
+
+  muted: boolean;
+  localAudioPublished: boolean;
+  /** true si le VADGate détecte de la parole active */
+  speaking: boolean;
+  /** True dès que getUserMedia a réussi, même si le transport n'est pas encore connecté. */
+  micReady?: boolean;
+
+  error?: {
+    code: string;
+    message: string;
+  };
+};
+
+export const initialAudioState: EphiaAudioState = {
+  permission: "unknown",
+  hasInputDevice: false,
+  level: 0,
+  rms: 0,
+  peak: 0,
+  isSilent: false,
+  silenceDurationMs: 0,
+  muted: false,
+  localAudioPublished: false,
+  speaking: false,
+};

package/src/shared/state/index.ts

@@ -0,0 +1,2 @@
+export { initialAudioState } from "./audio-state";
+export type { EphiaAudioPermission, EphiaAudioState } from "./audio-state";

package/src/shared/store/document-store.ts

@@ -0,0 +1,32 @@
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+
+export interface DocumentSection {
+  id: string;
+  title: string;
+  text: string;
+  level: number;
+  start: number;
+  end: number;
+}
+
+export interface DocumentStoreState {
+  content: string;
+  segments: DocumentSection[];
+  selectedText: string | null;
+  cursorSection: string | null;
+
+  syncFromEditor: (content: string, segments: DocumentSection[]) => void;
+  setSelection: (text: string | null, section: string | null) => void;
+}
+
+export const documentStore = create<DocumentStoreState>()(
+  subscribeWithSelector((set) => ({
+    content: "",
+    segments: [],
+    selectedText: null,
+    cursorSection: null,
+    syncFromEditor: (content, segments) => set({ content, segments }),
+    setSelection: (text, section) => set({ selectedText: text, cursorSection: section }),
+  }))
+);

package/src/shared/store/index.ts

@@ -0,0 +1,2 @@
+export { documentStore } from "./document-store";
+export type { DocumentSection, DocumentStoreState } from "./document-store";

package/src/shared/types/editors.ts

@@ -0,0 +1,28 @@
+// Duck-type minimal — pas d'import @codemirror/view pour ne pas créer de dépendance.
+export interface CMEditorView {
+  state: {
+    doc: { toString(): string; length: number };
+    selection: { main: { head: number; anchor: number; from: number; to: number; empty: boolean } };
+  };
+  dispatch(tr: object): void;
+  dom: HTMLElement;
+  contentDOM: HTMLElement;
+}
+
+// Duck-type minimal — pas d'import monaco-editor pour ne pas créer de dépendance.
+export interface MonacoEditorInstance {
+  getValue(): string;
+  getModel(): {
+    applyEdits(edits: Array<{ range: { startLineNumber: number; startColumn: number; endLineNumber: number; endColumn: number }; text: string }>): void;
+    getOffsetAt(position: { lineNumber: number; column: number }): number;
+    getPositionAt(offset: number): { lineNumber: number; column: number };
+    getValueLength(): number;
+  } | null;
+  getPosition(): { lineNumber: number; column: number } | null;
+  setPosition(position: { lineNumber: number; column: number }): void;
+  getSelection(): { isEmpty(): boolean; startLineNumber: number; startColumn: number; endLineNumber: number; endColumn: number } | null;
+  getDomNode(): HTMLElement | null;
+  getScrolledVisiblePosition(position: { lineNumber: number; column: number }): { top: number; left: number; height: number } | null;
+  executeEdits(source: string, edits: Array<{ range: { startLineNumber: number; startColumn: number; endLineNumber: number; endColumn: number }; text: string }>): boolean;
+  deltaDecorations(oldDecorations: string[], newDecorations: Array<{ range: { startLineNumber: number; startColumn: number; endLineNumber: number; endColumn: number }; options: { inlineClassName?: string; isWholeLine?: boolean } }>): string[];
+}

package/src/shared/types/session.ts

@@ -0,0 +1,12 @@
+/**
+ * Types pour la configuration d'une session de transcription.
+ */
+
+export type Mode = "fast_xs" | "fast_s" | "smart_xs" | "smart_s";
+
+export type EphiaSessionOptions = {
+  language?: string;
+  /** Mode global : fast_xs | fast_s | smart_xs | smart_s */
+  mode?: Mode;
+  debugChunks?: boolean;
+};

package/src/style.css

@@ -0,0 +1,2 @@
+@import "./ui/theme.css";
+@import "./react/ephia-react.css";