@ephia/dova-sdk 1.0.0

package/src/core/transcript/transcript.state.ts

@@ -0,0 +1,123 @@
+import type { EphiaAudioEvent, TranscriptSafetyMeta, TranscriptLayoutMeta } from "ephia-protocol";
+
+export type LiveTranscriptStatus =
+  | "idle"
+  | "connecting"
+  | "recording"
+  | "finalizing"
+  | "ended"
+  | "error";
+
+export type LiveTranscriptChunkStatus =
+  | "opened"
+  | "processing"
+  | "preview"
+  | "done"
+  | "error";
+
+export type LiveTranscriptChunk = {
+  segmentId: string;
+  segmentSeq: number;
+  status: LiveTranscriptChunkStatus;
+  text: string;
+  previewText?: string;
+  previewContinuesPreviousWord?: boolean;
+  stablePrefix?: string;
+  previewDelta?: string;
+  finalizedText?: string;
+  committedText?: string;
+  revision: number;
+  startedAtMs?: number;
+  audioClosedAtMs?: number;
+  endedAtMs?: number;
+  durationMs?: number;
+  provider?: string;
+  error?: string;
+  uncertain?: boolean;
+  reason?: string;
+  reasonCodes?: string[];
+  parseFallback?: boolean;
+  source?: string;
+  mergedWith?: string | string[];
+
+  // P1 backend : métadonnées additives — text/committedText/status restent
+  // la vérité affichable, ces champs ne servent qu'au debug/observabilité.
+  effectiveSource?: string;
+  correctionPending?: boolean;
+  correctionAccepted?: boolean;
+  correctionRejectedReason?: string | null;
+  commandsApplied?: string[];
+  normalizationsApplied?: string[];
+  safety?: TranscriptSafetyMeta;
+  layout?: TranscriptLayoutMeta;
+  rawStt?: string;
+  realtimeText?: string;
+  hintSentToSmall?: string | null;
+  fallbackText?: string | null;
+  smallRawText?: string;
+  correctionOutcome?: string;
+  debug?: Record<string, unknown>;
+};
+
+export type LiveTranscriptDiagnostics = {
+  mode?: "time" | "vad";
+  eventsCount: number;
+  chunksCount: number;
+  processingChunks: number;
+  doneChunks: number;
+  errorChunks: number;
+  seqValid: boolean;
+  lastProvider?: string;
+  lastLatencyMs?: number;
+  averageLatencyMs?: number;
+  finalTextLength: number;
+  previewActive: boolean;
+  uncertainChunks?: number;
+  parseFallbackChunks?: number;
+  contextChars?: number;
+};
+
+export type LiveTranscriptState = {
+  sessionId: string | null;
+  status: LiveTranscriptStatus;
+  events: EphiaAudioEvent[];
+  chunks: Record<string, LiveTranscriptChunk>;
+  orderedSegmentIds: string[];
+  finalText: string;
+  previewText: string;
+  displayText: string;
+  documentText: string;
+  lastEvent: EphiaAudioEvent | null;
+  diagnostics: LiveTranscriptDiagnostics;
+  error: { code: string; message: string } | null;
+  spinnerTick: number;
+  finalizedBeforeReset?: Record<string, true>;
+};
+
+export const initialLiveTranscriptState: LiveTranscriptState = {
+  sessionId: null,
+  status: "idle",
+  events: [],
+  chunks: {},
+  orderedSegmentIds: [],
+  finalText: "",
+  previewText: "",
+  displayText: "",
+  documentText: "",
+  lastEvent: null,
+  diagnostics: {
+    eventsCount: 0,
+    chunksCount: 0,
+    processingChunks: 0,
+    doneChunks: 0,
+    errorChunks: 0,
+    seqValid: true,
+    finalTextLength: 0,
+    previewActive: false,
+    uncertainChunks: 0,
+    parseFallbackChunks: 0,
+    contextChars: 0,
+  },
+  error: null,
+  spinnerTick: 0,
+};

package/src/core/transport/LiveKitTransport.publish.test.ts

@@ -0,0 +1,226 @@
+import { ConnectionState, Track } from "livekit-client";
+import { describe, expect, it, vi } from "vitest";
+import type { EphiaAudioEvent, EphiaServerEvent } from "ephia-protocol";
+import { LiveKitTransport } from "./LiveKitTransport";
+
+describe("LiveKitTransport publishAudio", () => {
+  it("publishes microphone track with Track.Source.Microphone", async () => {
+    const publishTrack = vi.fn(async () => ({ track: { label: "mic" } }));
+    const transport = new LiveKitTransport();
+    (transport as unknown as { room: unknown }).room = {
+      state: ConnectionState.Connected,
+      localParticipant: { publishTrack },
+    };
+
+    const mediaTrack = { label: "Default - MacBook Air Microphone" } as MediaStreamTrack;
+    await transport.publishAudio(mediaTrack);
+
+    expect(publishTrack).toHaveBeenCalledTimes(1);
+    const [, options] = publishTrack.mock.calls[0] as unknown as [MediaStreamTrack, { source?: Track.Source }];
+    expect(options.source).toBe(Track.Source.Microphone);
+  });
+});
+
+describe("LiveKitTransport client control wire", () => {
+  it("publishes sendMessage as a reliable V2 envelope on ephia.client.control", async () => {
+    const publishData = vi.fn(async () => undefined);
+    const transport = new LiveKitTransport();
+    (transport as unknown as { room: unknown; _sessionId: string }).room = {
+      state: ConnectionState.Connected,
+      localParticipant: { publishData },
+    };
+    (transport as unknown as { _sessionId: string })._sessionId = "session-1";
+
+    await transport.sendMessage({ type: "session.reset", payload: { contextOnly: true } });
+
+    expect(publishData).toHaveBeenCalledTimes(1);
+    const [encoded, options] = publishData.mock.calls[0] as unknown as [
+      Uint8Array,
+      { reliable?: boolean; topic?: string },
+    ];
+    const envelope = JSON.parse(new TextDecoder().decode(encoded));
+    expect(options).toEqual({ reliable: true, topic: "ephia.client.control" });
+    expect(envelope).toMatchObject({
+      protocolVersion: 2,
+      type: "session.reset",
+      sessionId: "session-1",
+      payload: { scope: "global", reason: "user_explicit" },
+    });
+    expect(envelope.clientSeq).toBe(1);
+  });
+});
+
+describe("LiveKitTransport session.reset wire payload", () => {
+  it("preserves scope=target, targetId and reason", async () => {
+    const publishData = vi.fn(async () => undefined);
+    const transport = new LiveKitTransport();
+    (transport as unknown as { room: unknown; _sessionId: string }).room = {
+      state: ConnectionState.Connected,
+      localParticipant: { publishData },
+    };
+    (transport as unknown as { _sessionId: string })._sessionId = "session-1";
+
+    await transport.sendMessage({
+      type: "session.reset",
+      payload: { scope: "target", targetId: "report", reason: "manual_edit" },
+    } as any);
+
+    expect(publishData).toHaveBeenCalledTimes(1);
+    const [encoded] = publishData.mock.calls[0] as unknown as [Uint8Array];
+    const envelope = JSON.parse(new TextDecoder().decode(encoded));
+    expect(envelope.payload).toEqual({ scope: "target", targetId: "report", reason: "manual_edit" });
+  });
+
+  it("preserves scope=global and reason", async () => {
+    const publishData = vi.fn(async () => undefined);
+    const transport = new LiveKitTransport();
+    (transport as unknown as { room: unknown; _sessionId: string }).room = {
+      state: ConnectionState.Connected,
+      localParticipant: { publishData },
+    };
+    (transport as unknown as { _sessionId: string })._sessionId = "session-1";
+
+    await transport.sendMessage({
+      type: "session.reset",
+      payload: { scope: "global", reason: "editor_empty" },
+    } as any);
+
+    const [encoded] = publishData.mock.calls[0] as unknown as [Uint8Array];
+    const envelope = JSON.parse(new TextDecoder().decode(encoded));
+    expect(envelope.payload).toEqual({ scope: "global", reason: "editor_empty" });
+  });
+
+  it("throws when scope=target is missing targetId", async () => {
+    const publishData = vi.fn(async () => undefined);
+    const transport = new LiveKitTransport();
+    (transport as unknown as { room: unknown; _sessionId: string }).room = {
+      state: ConnectionState.Connected,
+      localParticipant: { publishData },
+    };
+    (transport as unknown as { _sessionId: string })._sessionId = "session-1";
+
+    await expect(
+      transport.sendMessage({
+        type: "session.reset",
+        payload: { scope: "target", reason: "user_explicit" },
+      } as any)
+    ).rejects.toThrow();
+  });
+});
+
+describe("LiveKitTransport wire event routing", () => {
+  it("forwards V2 segment.operation via onServerEvent without legacy synthesis", () => {
+    const transport = new LiveKitTransport();
+    const serverEvents: EphiaServerEvent[] = [];
+    const legacyEvents: EphiaAudioEvent[] = [];
+    transport.onServerEvent((event) => serverEvents.push(event));
+    transport.onEvent((event) => legacyEvents.push(event));
+
+    (transport as unknown as {
+      _handleWireServerEvent(event: unknown): void;
+    })._handleWireServerEvent(
+      {
+        protocolVersion: 2,
+        type: "segment.operation",
+        eventId: "evt-1",
+        sessionId: "session-1",
+        serverSeq: 9,
+        sentAt: "2026-06-17T00:00:00+00:00",
+        payload: {
+          segmentId: "seg-1",
+          segmentSeq: 1,
+          segmentRevision: 9,
+          targetId: "report",
+          operation: "upsert",
+          stage: "canonical",
+          text: "Compte rendu.",
+          textForInsertion: "Compte rendu.",
+          source: "dova-medical",
+          safety: { decision: "accept", score: 0 },
+          debug: { rawStt: "compte rendu" },
+        },
+      }
+    );
+
+    expect(serverEvents).toHaveLength(1);
+    expect(serverEvents[0]?.type).toBe("segment.operation");
+    expect(legacyEvents).toHaveLength(0);
+  });
+
+  it("emits raw EphiaServerEvent via onServerEvent (V2 path, no inference)", () => {
+    const transport = new LiveKitTransport();
+    const serverEvents: EphiaServerEvent[] = [];
+    transport.onServerEvent((event) => serverEvents.push(event));
+
+    const wireEvent = {
+      protocolVersion: 2 as const,
+      type: "segment.operation" as const,
+      eventId: "evt-2",
+      sessionId: "session-1",
+      serverSeq: 10,
+      sentAt: "2026-06-17T00:00:00+00:00",
+      payload: {
+        segmentId: "seg-2",
+        segmentSeq: 2,
+        segmentRevision: 1,
+        targetId: "report",
+        operation: "upsert" as const,
+        stage: "provisional" as const,
+        text: "Acquisition.",
+        textForInsertion: "Acquisition.",
+        source: "dova-real-time" as const,
+      },
+    };
+
+    (transport as unknown as {
+      _handleWireServerEvent(event: unknown): void;
+    })._handleWireServerEvent(wireEvent);
+
+    expect(serverEvents).toHaveLength(1);
+    const emitted = serverEvents[0]!;
+    expect(emitted.type).toBe("segment.operation");
+    if (emitted.type === "segment.operation") {
+      expect(emitted.payload.segmentId).toBe("seg-2");
+      expect(emitted.payload.stage).toBe("provisional");
+      expect(emitted.payload.targetId).toBe("report");
+      expect(emitted.serverSeq).toBe(10);
+    }
+  });
+
+  it("emits segment.operation with absorbedSegmentIds via onServerEvent", () => {
+    const transport = new LiveKitTransport();
+    const serverEvents: EphiaServerEvent[] = [];
+    transport.onServerEvent((event) => serverEvents.push(event));
+
+    (transport as unknown as {
+      _handleWireServerEvent(event: unknown): void;
+    })._handleWireServerEvent(
+      {
+        protocolVersion: 2,
+        type: "segment.operation",
+        eventId: "evt-3",
+        sessionId: "session-1",
+        serverSeq: 11,
+        sentAt: "2026-06-17T00:00:00+00:00",
+        payload: {
+          segmentId: "seg-prev",
+          segmentSeq: 3,
+          segmentRevision: 2,
+          targetId: "report",
+          operation: "upsert",
+          stage: "canonical",
+          text: "Texte fusionné.",
+          textForInsertion: "Texte fusionné.",
+          source: "dova-medical",
+          absorbedSegmentIds: ["seg-cur"],
+        },
+      }
+    );
+
+    const emitted = serverEvents[0];
+    expect(emitted?.type).toBe("segment.operation");
+    if (emitted?.type === "segment.operation") {
+      expect(emitted.payload.absorbedSegmentIds).toEqual(["seg-cur"]);
+    }
+  });
+});