@ephia/dova-sdk 1.0.0

package/src/core/client/session-api.ts

@@ -0,0 +1,415 @@
+/**
+ * SessionApiClient — HTTP vers le backend Ephia (sessions, tokens, preload).
+ *
+ * Rôle : createSession, refreshToken, stopBackendSession, preload.
+ * Possède : session préchargée et timers de refresh preload.
+ * Ne fait pas : transport LiveKit, routing events.
+ */
+
+import { z } from "zod";
+import type { EphiaSessionOptions } from "../../shared/types/session";
+import { EphiaSdkError } from "../../shared/errors/EphiaSdkError";
+import { resolveEphiaSdkApiUrl } from "../../shared/config/endpoint";
+import type { EphiaStartOptions } from "./client-options";
+import {
+  ACTIVE_TOKEN_TTL_MS,
+  AUDIO_SESSIONS_PATH,
+  PROTOCOL_VERSION,
+  SDK_VERSION,
+  TOKEN_MAX_AGE_MS,
+} from "./constants";
+
+const createSessionResponseSchema = z.object({
+  session_id: z.string(),
+  room_name: z.string(),
+  token: z.string(),
+  livekit_url: z.string(),
+  protocol_version: z.string().optional(),
+  capabilities: z
+    .object({
+      supports_realtime: z.boolean().optional(),
+    })
+    .optional(),
+});
+
+export type SessionCredentials = {
+  sessionId: string;
+  roomName: string;
+  token: string;
+  livekitUrl: string;
+};
+
+type PreloadedSession = SessionCredentials & {
+  createdAt: number;
+  initialTargetId?: string;
+};
+
+export type SessionApiClientOptions = {
+  apiUrl?: string;
+  apiKey?: string;
+  bearerToken?: string;
+  clientType?: string;
+  sessionOptions?: EphiaSessionOptions;
+  onPrepareConnection?: (livekitUrl: string, token: string) => void;
+  onPreloadComplete?: (data: SessionCredentials) => void;
+  onPreloadFailed?: () => void;
+  isIdle?: () => boolean;
+};
+
+export class SessionApiClient {
+  private readonly opts: SessionApiClientOptions;
+  private _preloadedSession: PreloadedSession | null = null;
+  private _preloadPromise: Promise<void> | null = null;
+  private _preloadToken = 0;
+  private _preloadRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(opts: SessionApiClientOptions) {
+    this.opts = opts;
+  }
+
+  get preloadedSession(): PreloadedSession | null {
+    return this._preloadedSession;
+  }
+
+  get preloadToken(): number {
+    return this._preloadToken;
+  }
+
+  incrementPreloadToken(): void {
+    this._preloadToken++;
+  }
+
+  takePreloadedSession(): SessionCredentials | null {
+    const s = this._preloadedSession;
+    if (!s) return null;
+    this._preloadedSession = null;
+    return {
+      sessionId: s.sessionId,
+      roomName: s.roomName,
+      token: s.token,
+      livekitUrl: s.livekitUrl,
+    };
+  }
+
+  discardPreloadedSession(): PreloadedSession | null {
+    const s = this._preloadedSession;
+    this._preloadedSession = null;
+    return s;
+  }
+
+  clearPreloadPromise(): void {
+    this._preloadPromise = null;
+  }
+
+  hasPreloadInFlight(): boolean {
+    return this._preloadPromise !== null;
+  }
+
+  async awaitPreloadIfPending(signal?: AbortSignal): Promise<void> {
+    const preloadPromise = this._preloadPromise;
+    if (!preloadPromise) return;
+    if (signal?.aborted) {
+      throw new EphiaSdkError("client.start_failed", "Start aborted");
+    }
+    if (!signal) {
+      await preloadPromise;
+      return;
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const onAbort = () => {
+        signal.removeEventListener("abort", onAbort);
+        reject(new EphiaSdkError("client.start_failed", "Start aborted"));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      preloadPromise.then(
+        () => {
+          signal.removeEventListener("abort", onAbort);
+          resolve();
+        },
+        (err) => {
+          signal.removeEventListener("abort", onAbort);
+          reject(err);
+        }
+      );
+    });
+  }
+
+  cancelTimers(): void {
+    if (this._preloadRefreshTimer !== null) {
+      clearTimeout(this._preloadRefreshTimer);
+      this._preloadRefreshTimer = null;
+    }
+  }
+
+  async preload(signal?: AbortSignal): Promise<void>;
+  async preload(options?: EphiaStartOptions, signal?: AbortSignal): Promise<void>;
+  async preload(
+    optionsOrSignal?: EphiaStartOptions | AbortSignal,
+    maybeSignal?: AbortSignal
+  ): Promise<void> {
+    const signal =
+      optionsOrSignal && "aborted" in optionsOrSignal ? optionsOrSignal : maybeSignal;
+    const startOptions =
+      optionsOrSignal && !("aborted" in optionsOrSignal) ? optionsOrSignal : undefined;
+    if (this.opts.isIdle && !this.opts.isIdle()) {
+      console.info("[EphiaAudioClient] preload: skipped, not idle");
+      return;
+    }
+    if (this._preloadedSession) {
+      console.info(
+        "[EphiaAudioClient] preload: already preloaded",
+        this._preloadedSession.sessionId
+      );
+      return;
+    }
+    if (this._preloadPromise) {
+      return this._preloadPromise;
+    }
+
+    const token = ++this._preloadToken;
+    const preloadPromise = this.createSession(signal, startOptions)
+      .then((data) => {
+        if (token !== this._preloadToken) {
+          void this.stopBackendSession(data.sessionId);
+          return;
+        }
+        this._preloadedSession = {
+          ...data,
+          createdAt: Date.now(),
+          initialTargetId: startOptions?.initialTargetId,
+        };
+        this.opts.onPrepareConnection?.(data.livekitUrl, data.token);
+        this.opts.onPreloadComplete?.(data);
+        console.info("[EphiaAudioClient] preload:done", data.sessionId);
+        this.schedulePreloadRefresh();
+      })
+      .catch((err) => {
+        if (err instanceof Error && err.name === "AbortError") return;
+        console.warn("[EphiaAudioClient] preload:failed", err);
+        this.opts.onPreloadFailed?.();
+      })
+      .finally(() => {
+        if (this._preloadPromise === preloadPromise) {
+          this._preloadPromise = null;
+        }
+      });
+
+    this._preloadPromise = preloadPromise;
+    return this._preloadPromise;
+  }
+
+  schedulePreloadRefresh(): void {
+    if (this._preloadRefreshTimer !== null) {
+      clearTimeout(this._preloadRefreshTimer);
+    }
+    this._preloadRefreshTimer = setTimeout(() => {
+      this._preloadRefreshTimer = null;
+      if (this.opts.isIdle?.()) {
+        console.info("[EphiaAudioClient] preload: auto-refreshing expired token");
+        const orphaned = this.discardPreloadedSession();
+        if (orphaned) {
+          void this.stopBackendSession(orphaned.sessionId);
+        }
+        this._preloadPromise = null;
+        // Preserve initialTargetId from the previous preloaded session.
+        const options = orphaned?.initialTargetId
+          ? { initialTargetId: orphaned.initialTargetId }
+          : undefined;
+        void this.preload(options).catch(() => {});
+      }
+    }, TOKEN_MAX_AGE_MS * 0.8);
+  }
+
+  /** Refresh token LiveKit — retourne le nouveau token ou null. */
+  async refreshToken(sessionId: string): Promise<string | null> {
+    const apiUrl = resolveEphiaSdkApiUrl(this.opts.apiUrl);
+    const headers = this.authHeaders();
+    try {
+      const r = await fetch(
+        `${apiUrl}${AUDIO_SESSIONS_PATH}/${encodeURIComponent(sessionId)}/token`,
+        { headers }
+      );
+      const data = (await r.json()) as { token?: string };
+      if (data.token) {
+        console.info("[EphiaAudioClient] token refreshed for next reconnect", sessionId);
+        return data.token;
+      }
+    } catch (err) {
+      console.warn("[EphiaAudioClient] token refresh failed (non-fatal)", err);
+    }
+    return null;
+  }
+
+  get activeTokenRefreshDelayMs(): number {
+    return ACTIVE_TOKEN_TTL_MS * 0.8;
+  }
+
+  isPreloadedSessionExpired(): boolean {
+    if (!this._preloadedSession) return false;
+    return Date.now() - this._preloadedSession.createdAt > TOKEN_MAX_AGE_MS;
+  }
+
+  async createSessionWithRetry(
+    signal?: AbortSignal,
+    startOptions?: EphiaStartOptions
+  ): Promise<SessionCredentials> {
+    const maxRetries = 2;
+    let lastErr: unknown;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      if (signal?.aborted) {
+        throw new EphiaSdkError("client.start_failed", "Start aborted");
+      }
+      try {
+        return await this.createSession(signal, startOptions);
+      } catch (err) {
+        lastErr = err;
+        if (err instanceof EphiaSdkError) throw err;
+        if (signal?.aborted) throw err;
+        if (attempt < maxRetries) {
+          const delay = 250 * Math.pow(2, attempt) + Math.random() * 100;
+          console.warn(
+            `[EphiaAudioClient] createSession:retry attempt=${attempt + 1} delay=${Math.round(delay)}ms`,
+            err
+          );
+          await new Promise<void>((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    throw lastErr;
+  }
+
+  async createSession(
+    signal?: AbortSignal,
+    startOptions?: EphiaStartOptions
+  ): Promise<SessionCredentials> {
+    const apiUrl = resolveEphiaSdkApiUrl(this.opts.apiUrl);
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...this.authHeaders(),
+    };
+
+    const so = this.opts.sessionOptions;
+    const body: Record<string, unknown> = {
+      session_mode: "dictation",
+      client_type: this.opts.clientType ?? "sdk",
+      language: so?.language ?? "fr",
+      mode: so?.mode ?? "smart_s",
+      debug_chunks: so?.debugChunks ?? false,
+      sdk_version: SDK_VERSION,
+      protocol_version: String(PROTOCOL_VERSION),
+    };
+    if (startOptions?.initialTargetId) {
+      body.initial_target_id = startOptions.initialTargetId;
+    }
+
+    const response = await fetch(`${apiUrl}${AUDIO_SESSIONS_PATH}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal,
+    });
+
+    const rawText = await response.text();
+    if (!response.ok) {
+      let message = `Failed to create session: ${response.statusText}`;
+      try {
+        const errBody = JSON.parse(rawText) as {
+          detail?:
+            | string
+            | { message?: string; hint?: string }
+            | Array<{
+                loc?: Array<string | number>;
+                msg?: string;
+                type?: string;
+              }>;
+        };
+        const detail = errBody.detail;
+        if (typeof detail === "string") {
+          message = detail;
+        } else if (Array.isArray(detail)) {
+          message = detail
+            .map((item) => {
+              const loc = item.loc?.join(".") ?? "body";
+              return `${loc}: ${item.msg ?? item.type ?? "validation error"}`;
+            })
+            .join(" — ");
+        } else if (detail && typeof detail === "object") {
+          const parts = [detail.message, detail.hint].filter(Boolean);
+          if (parts.length > 0) message = parts.join(" — ");
+        }
+      } catch {
+        if (rawText) message = rawText;
+      }
+      throw new EphiaSdkError("session.create_failed", message, {
+        status: response.status,
+      });
+    }
+
+    const parsed = createSessionResponseSchema.safeParse(JSON.parse(rawText) as unknown);
+    if (!parsed.success) {
+      throw new EphiaSdkError(
+        "session.create_failed",
+        "Invalid session response from backend",
+        { issues: parsed.error.issues }
+      );
+    }
+
+    return {
+      sessionId: parsed.data.session_id,
+      roomName: parsed.data.room_name,
+      token: parsed.data.token,
+      livekitUrl: parsed.data.livekit_url,
+    };
+  }
+
+  async stopBackendSession(sessionId: string): Promise<void> {
+    try {
+      const apiUrl = resolveEphiaSdkApiUrl(this.opts.apiUrl);
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        ...this.authHeaders(),
+      };
+      await fetch(`${apiUrl}${AUDIO_SESSIONS_PATH}/${encodeURIComponent(sessionId)}/stop`, {
+        method: "POST",
+        headers,
+      });
+      console.info("[EphiaAudioClient] stopBackendSession:done", sessionId);
+    } catch (err) {
+      console.warn("[EphiaAudioClient] stopBackendSession:failed", sessionId, err);
+    }
+  }
+
+  /** Best-effort stop on tab close (fetch keepalive supports auth headers). */
+  stopBackendSessionOnPageHide(sessionId: string): void {
+    if (typeof window === "undefined" || !sessionId) return;
+    try {
+      const apiUrl = resolveEphiaSdkApiUrl(this.opts.apiUrl);
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        ...this.authHeaders(),
+      };
+      void fetch(`${apiUrl}${AUDIO_SESSIONS_PATH}/${encodeURIComponent(sessionId)}/stop`, {
+        method: "POST",
+        headers,
+        keepalive: true,
+      });
+    } catch {
+      /* ignore */
+    }
+  }
+
+  private authHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {};
+    if (this.opts.apiKey) {
+      headers["X-API-Key"] = this.opts.apiKey;
+    } else if (this.opts.bearerToken) {
+      headers["Authorization"] = `Bearer ${this.opts.bearerToken}`;
+    }
+    if (this.opts.clientType) {
+      headers["X-Ephia-Client"] = this.opts.clientType;
+      headers["X-Ephia-App"] = this.opts.clientType;
+    }
+    return headers;
+  }
+}

package/src/core/connection/connection-state.ts

@@ -0,0 +1,78 @@
+/**
+ * État de connexion transport + qualité.
+ *
+ * Source de vérité pour les composants UI de connexion.
+ * Alimenté par LiveKitTransport via un mapper depuis TransportState.
+ */
+
+import type { TransportState } from "../transport/Transport";
+
+export type EphiaConnectionStatus =
+  | "idle"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "reconnected"
+  | "disconnected"
+  | "error";
+
+export type EphiaConnectionQuality = "unknown" | "poor" | "good" | "excellent";
+
+export type EphiaConnectionState = {
+  status: EphiaConnectionStatus;
+  quality: EphiaConnectionQuality;
+
+  roomName?: string;
+  participantIdentity?: string;
+
+  reconnectCount: number;
+  lastConnectedAt?: number;
+  lastReconnectedAt?: number;
+  lastDisconnectedAt?: number;
+
+  localAudioPublished: boolean;
+  localAudioMuted: boolean;
+
+  dataChannelReady: boolean;
+
+  lastError?: {
+    code: string;
+    message: string;
+  };
+};
+
+export const initialConnectionState: EphiaConnectionState = {
+  status: "idle",
+  quality: "unknown",
+  localAudioPublished: false,
+  localAudioMuted: false,
+  reconnectCount: 0,
+  dataChannelReady: false,
+};
+
+export function mapTransportStateToConnectionState(
+  ts: TransportState,
+  prev?: EphiaConnectionState
+): EphiaConnectionState {
+  const now = Date.now();
+  const next: EphiaConnectionState = {
+    status: ts.status,
+    quality: ts.connectionQuality ?? "unknown",
+    roomName: ts.roomName,
+    participantIdentity: ts.participantIdentity,
+    reconnectCount: ts.reconnectCount,
+    localAudioPublished: ts.localAudioPublished,
+    localAudioMuted: ts.localAudioMuted,
+    dataChannelReady: ts.status === "connected" || ts.status === "reconnected",
+    lastError: ts.lastError
+      ? { code: ts.lastError.code, message: ts.lastError.message }
+      : undefined,
+    lastConnectedAt:
+      ts.status === "connected" ? now : prev?.lastConnectedAt,
+    lastReconnectedAt:
+      ts.status === "reconnected" ? now : prev?.lastReconnectedAt,
+    lastDisconnectedAt:
+      ts.status === "disconnected" ? now : prev?.lastDisconnectedAt,
+  };
+  return next;
+}

package/src/core/connection/index.ts

@@ -0,0 +1,6 @@
+export { initialConnectionState, mapTransportStateToConnectionState } from "./connection-state";
+export type {
+  EphiaConnectionQuality,
+  EphiaConnectionState,
+  EphiaConnectionStatus,
+} from "./connection-state";

package/src/core/index.ts

@@ -0,0 +1,47 @@
+// Client (types only — EphiaAudioClient is internal)
+export type { EphiaAudioClientOptions, EphiaStartOptions } from "./client/EphiaAudioClient";
+export type { EphiaClientState, EphiaClientStatus } from "./client/client-state";
+export { initialClientState } from "./client/client-state";
+
+// Transport
+export type { Transport, TransportState, TransportConnectParams } from "./transport/Transport";
+export { LiveKitTransport } from "./transport/LiveKitTransport";
+export { MockTransport } from "./transport/MockTransport";
+
+// Transcript state & reducers (still used by some internal apps)
+export { eventReducer } from "./transcript/client-transcript.reducer";
+export { liveTranscriptReducer } from "./transcript/transcript.reducer";
+export type { LiveTranscriptAction } from "./transcript/transcript.reducer";
+export type { TranscriptState, TranscriptSegment } from "./transcript/client-transcript.state";
+export { initialTranscriptState } from "./transcript/client-transcript.state";
+export type { LiveTranscriptState, LiveTranscriptChunk, LiveTranscriptDiagnostics } from "./transcript/transcript.state";
+export { initialLiveTranscriptState } from "./transcript/transcript.state";
+export { assembleTranscript, assembleCommittedDocument, buildDisplayText } from "./transcript/transcript.assembler";
+
+// Runtime (TranscriptApplier is public; DictationRuntime is deprecated but still exported for internal compat)
+export { TranscriptApplier } from "./runtime/TranscriptApplier";
+export type { TranscriptApplierOptions } from "./runtime/TranscriptApplier";
+
+// Targets V2
+export {
+  EditorContextCollector,
+  TargetManager,
+} from "./targets";
+export type {
+  EditorContextCollectorOptions,
+  EditorContextTarget,
+  ManagedTarget,
+  TargetManagerOptions,
+} from "./targets";
+
+// Operations
+export type { TextToDocumentOperationsOptions } from "./operations/textToDocumentOperations";
+export { textToDocumentOperations, documentOperationsToPlainText } from "./operations/textToDocumentOperations";
+
+// Session
+export { transitionSessionStatus, canTransition } from "./session/session-machine";
+export type { EphiaSessionStatus } from "./session/session-machine";
+
+// Connection state
+export { mapTransportStateToConnectionState, initialConnectionState } from "./connection/connection-state";
+export type { EphiaConnectionState, EphiaConnectionStatus, EphiaConnectionQuality } from "./connection/connection-state";

package/src/core/operations/textToDocumentOperations.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { DOCUMENT_OPERATION_TYPES, type DocumentOperation } from "ephia-protocol";
+import { documentOperationsToPlainText, textToDocumentOperations } from "./textToDocumentOperations";
+
+describe("textToDocumentOperations", () => {
+  it("converts a single \\n into a line_break operation", () => {
+    const ops = textToDocumentOperations("Indication :\nrésultat normal");
+    expect(ops.map((o) => o.type)).toEqual(["insert_text", "line_break", "insert_text"]);
+  });
+
+  it("converts \\n\\n into a paragraph_break operation", () => {
+    const ops = textToDocumentOperations("Contexte.\n\nRésultat : pas de foyer.");
+    expect(ops.map((o) => o.type)).toEqual(["insert_text", "paragraph_break", "insert_text"]);
+  });
+
+  it("produces a single insert_text for flat text with no breaks", () => {
+    const ops = textToDocumentOperations("Pas de saignement.");
+    expect(ops).toHaveLength(1);
+    expect(ops[0].type).toBe("insert_text");
+  });
+
+  it("applies the given position to every operation", () => {
+    const ops = textToDocumentOperations("a\nb", { position: "end" });
+    for (const op of ops) {
+      expect((op as { position?: unknown }).position).toBe("end");
+    }
+  });
+
+  it("defaults position to cursor", () => {
+    const ops = textToDocumentOperations("a\nb");
+    for (const op of ops) {
+      expect((op as { position?: unknown }).position).toBe("cursor");
+    }
+  });
+});
+
+describe("documentOperationsToPlainText", () => {
+  it("round-trips text containing line and paragraph breaks", () => {
+    const original = "Indication :\nTraumatisme.\n\nRésultat : pas de foyer.";
+    const ops = textToDocumentOperations(original);
+    expect(documentOperationsToPlainText(ops)).toBe(original);
+  });
+
+  it("round-trips flat text with no breaks", () => {
+    const original = "Pas de saignement intra ou extra axial.";
+    const ops = textToDocumentOperations(original);
+    expect(documentOperationsToPlainText(ops)).toBe(original);
+  });
+
+  it("ignores operations without a plain-text representation", () => {
+    const ops: DocumentOperation[] = [
+      { id: "1", type: "insert_text", position: "cursor", text: "a" },
+      { id: "2", type: "highlight", reason: "x", severity: "info" },
+      { id: "3", type: "insert_text", position: "cursor", text: "b" },
+    ];
+    expect(documentOperationsToPlainText(ops)).toBe("ab");
+  });
+});
+
+describe("DOCUMENT_OPERATION_TYPES stays in sync with the DocumentOperation union", () => {
+  it("includes line_break and paragraph_break", () => {
+    expect(DOCUMENT_OPERATION_TYPES).toContain("line_break");
+    expect(DOCUMENT_OPERATION_TYPES).toContain("paragraph_break");
+  });
+
+  it("has no duplicate entries", () => {
+    expect(new Set(DOCUMENT_OPERATION_TYPES).size).toBe(DOCUMENT_OPERATION_TYPES.length);
+  });
+});