@ephia/dova-sdk 1.0.0

package/src/core/transport/LiveKitTransport.ts

@@ -0,0 +1,459 @@
+/**
+ * Transport LiveKit — implémentation du Transport Ephia pour l'agent ephia-transcribe-agent.
+ *
+ * Wire V2 :
+ *   • SDK → backend : ephia.client.control
+ *   • backend → SDK : ephia.server.event
+ */
+
+import {
+  Room,
+  RoomEvent,
+  DataPacket_Kind,
+  LocalAudioTrack,
+  LocalTrackPublication,
+  ConnectionState,
+  ConnectionQuality,
+  MediaDeviceFailure,
+  AudioPresets,
+  Track,
+} from "livekit-client";
+import type { ReconnectContext, ReconnectPolicy } from "livekit-client";
+import type {
+  EphiaAudioEvent,
+  EphiaClientMessage,
+  EphiaServerEvent,
+} from "ephia-protocol";
+import { ephiaWireServerEventSchema, PROTOCOL_VERSION } from "ephia-protocol";
+import { EphiaSdkError } from "../../shared/errors/EphiaSdkError";
+import { dbgRawEvent, dbgState } from "../../debug/sdk-debug-collector";
+import type {
+  Transport,
+  TransportConnectParams,
+  TransportState,
+} from "./Transport";
+
+const TOPIC_CLIENT_CONTROL = "ephia.client.control";
+const TOPIC_SERVER_EVENT = "ephia.server.event";
+const TRACK_MIC = "ephia-microphone";
+
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+
+// P1 backend : parsing défensif des champs additifs optionnels du payload
+// JSON brut (snake_case) — le backend peut omettre ces champs (versions
+// antérieures, fallback) sans que le transport ne plante.
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+const RECONNECT_POLICY: ReconnectPolicy = {
+  nextRetryDelayInMs(ctx: ReconnectContext): number | null {
+    if (ctx.retryCount >= 10) return null;
+    const base = Math.min(300 * 2 ** ctx.retryCount, 30_000);
+    const jitter = Math.floor(Math.random() * 1000);
+    return base + jitter;
+  },
+};
+
+function uuid(): string {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+export class LiveKitTransport implements Transport {
+  private room: Room | null = null;
+  private _eventCallbacks: Set<(event: EphiaAudioEvent) => void> = new Set();
+  private _serverEventCallbacks: Set<(event: EphiaServerEvent) => void> = new Set();
+  private _stateCallbacks: Set<(state: TransportState) => void> = new Set();
+  private _errorCallbacks: Set<(error: EphiaSdkError) => void> = new Set();
+  private _state: TransportState = {
+    status: "idle",
+    localAudioPublished: false,
+    localAudioMuted: false,
+    reconnectCount: 0,
+  };
+  private _localAudioTrack: LocalTrackPublication | null = null;
+  private _krispProcessor: { destroy?: () => void } | null = null;
+
+  private _sessionId = "";
+  private _clientSeq = 0;
+
+  async connect(params: TransportConnectParams): Promise<void> {
+    if (!this.room) {
+      this.room = new Room(this._roomOptions());
+    } else if (
+      this.room.state === ConnectionState.Connected ||
+      this.room.state === ConnectionState.Reconnecting ||
+      this.room.state === ConnectionState.Connecting
+    ) {
+      await this.disconnect("reconnect");
+      this.room = new Room(this._roomOptions());
+    } else {
+      this.room.removeAllListeners();
+    }
+
+    this._sessionId = (params as any).sessionId ?? params.roomName;
+    this._clientSeq = 0;
+
+    this._setState({ status: "connecting", roomName: params.roomName });
+    this._attachRoomListeners(params);
+    await this.room.connect(params.livekitUrl, params.token);
+
+    if (this.room.state !== ConnectionState.Connected) {
+      throw new EphiaSdkError(
+        "transport.connect_failed",
+        `LiveKit room not connected: ${this.room.state}`
+      );
+    }
+
+    this._setState({
+      status: "connected",
+      roomName: this.room.name,
+      participantIdentity: this.room.localParticipant?.identity,
+    });
+
+  }
+
+  async prepareConnection(url: string, token?: string): Promise<void> {
+    if (!this.room) {
+      this.room = new Room(this._roomOptions());
+    }
+    await this.room.prepareConnection(url, token);
+  }
+
+  async disconnect(_reason?: string): Promise<void> {
+    if (this.room) {
+      const room = this.room;
+      await room.disconnect();
+      room.removeAllListeners();
+      this.room = null;
+    }
+    this._localAudioTrack = null;
+    this._setState({
+      status: "disconnected",
+      localAudioPublished: false,
+      localAudioMuted: false,
+    });
+  }
+
+  async sendMessage(message: EphiaClientMessage): Promise<void> {
+    if (!this.room) {
+      throw new EphiaSdkError("transport.not_connected", "Cannot send message: room is null");
+    }
+    if (this.room.state !== ConnectionState.Connected) {
+      throw new EphiaSdkError("transport.not_connected", `Cannot send message: room state is ${this.room.state}`);
+    }
+
+    const wire = this._toWireClientEvent(message);
+    await this.room.localParticipant.publishData(textEncoder.encode(JSON.stringify(wire)), {
+      reliable: true,
+      topic: TOPIC_CLIENT_CONTROL,
+    });
+  }
+
+  onEvent(callback: (event: EphiaAudioEvent) => void): () => void {
+    this._eventCallbacks.add(callback);
+    return () => this._eventCallbacks.delete(callback);
+  }
+
+  onServerEvent(callback: (event: EphiaServerEvent) => void): () => void {
+    this._serverEventCallbacks.add(callback);
+    return () => this._serverEventCallbacks.delete(callback);
+  }
+
+  onTransportState(callback: (state: TransportState) => void): () => void {
+    this._stateCallbacks.add(callback);
+    return () => this._stateCallbacks.delete(callback);
+  }
+
+  onError(callback: (error: EphiaSdkError) => void): () => void {
+    this._errorCallbacks.add(callback);
+    return () => this._errorCallbacks.delete(callback);
+  }
+
+  getState(): TransportState {
+    return { ...this._state };
+  }
+
+  getLocalAudioPublication(): LocalTrackPublication | null {
+    return this._localAudioTrack;
+  }
+
+  async publishAudio(track: MediaStreamTrack, options?: { enableNoiseFilter?: boolean }): Promise<void> {
+    if (this._localAudioTrack) {
+      await this.unpublishAudio();
+    }
+    if (!this.room) {
+      throw new EphiaSdkError("transport.connect_failed", "Cannot publish audio: room is null");
+    }
+    if (this.room.state !== ConnectionState.Connected) {
+      throw new EphiaSdkError("transport.connect_failed", `Room not connected: ${this.room.state}`);
+    }
+
+    this._localAudioTrack = await this.room.localParticipant.publishTrack(track, {
+      name: TRACK_MIC,
+      source: Track.Source.Microphone,
+      audioPreset: AudioPresets.speech,
+    } as any);
+
+    this._setState({ localAudioMuted: false });
+
+    const tryKrisp = options?.enableNoiseFilter === true;
+    if (tryKrisp && this._localAudioTrack?.track instanceof LocalAudioTrack) {
+      try {
+        const { KrispNoiseFilter, isKrispNoiseFilterSupported } = await import("@livekit/krisp-noise-filter");
+        if (isKrispNoiseFilterSupported()) {
+          const processor = KrispNoiseFilter();
+          await this._localAudioTrack.track.setProcessor(processor);
+          this._krispProcessor = processor;
+          await track.applyConstraints({
+            echoCancellation: false,
+            noiseSuppression: false,
+            autoGainControl: false,
+          });
+          this._setState({ krispActive: true });
+        }
+      } catch (err) {
+        console.warn("[LiveKitTransport] Krisp initialization failed — fallback WebRTC natif", err);
+      }
+    }
+  }
+
+  async unpublishAudio(): Promise<void> {
+    if (this._localAudioTrack && this.room) {
+      if (this._krispProcessor && this._localAudioTrack.track instanceof LocalAudioTrack) {
+        try {
+          await this._localAudioTrack.track.stopProcessor();
+        } catch { /* ignore */ }
+        this._krispProcessor = null;
+      }
+      await this.room.localParticipant.unpublishTrack(this._localAudioTrack.track!);
+      this._localAudioTrack = null;
+      this._setState({ krispActive: false, localAudioMuted: false });
+    }
+  }
+
+  async performRpc(method: string, payload: unknown, timeout = 3000): Promise<string> {
+    if (!this.room) {
+      throw new EphiaSdkError("transport.not_connected", "Cannot perform RPC: room not available");
+    }
+    return this.room.localParticipant.performRpc({
+      destinationIdentity: "ephia-transcribe-agent",
+      method,
+      payload: JSON.stringify(payload),
+      responseTimeout: timeout,
+    });
+  }
+
+  async switchActiveDevice(kind: MediaDeviceKind, deviceId: string): Promise<boolean> {
+    if (!this.room) {
+      throw new EphiaSdkError("transport.not_connected", "Cannot switch device: room not available");
+    }
+    return this.room.switchActiveDevice(kind, deviceId);
+  }
+
+  // ------------------------------------------------------------------
+  // Internals
+  // ------------------------------------------------------------------
+
+  private _toWireClientEvent(message: EphiaClientMessage): Record<string, unknown> {
+    const msgType = (message as { type: string }).type;
+    return {
+      protocolVersion: PROTOCOL_VERSION,
+      type: msgType,
+      eventId: uuid(),
+      sessionId: this._sessionId,
+      clientSeq: ++this._clientSeq,
+      sentAt: new Date().toISOString(),
+      payload: this._toWireClientPayload(message),
+    };
+  }
+
+  private _toWireClientPayload(message: EphiaClientMessage): Record<string, unknown> {
+    const msgType = (message as { type: string }).type;
+    const payload = (message as { payload?: unknown }).payload;
+    const raw = payload && typeof payload === "object" && !Array.isArray(payload)
+      ? (payload as Record<string, unknown>)
+      : {};
+
+    if (msgType === "session.reset") {
+      const scope = raw.scope === "target" ? "target" : "global";
+      const targetId = asString(raw.targetId) ?? asString(raw.target_id);
+      const reason = asString(raw.reason) ?? "user_explicit";
+
+      if (scope === "target" && !targetId) {
+        throw new EphiaSdkError(
+          "protocol.invalid_event",
+          "session.reset target scope requires targetId"
+        );
+      }
+
+      return scope === "target" && targetId
+        ? { scope: "target", targetId, reason }
+        : { scope: "global", reason };
+    }
+
+    if (msgType === "session.target.changed") {
+      return { targetId: asString(raw.targetId) ?? asString(raw.target_id) ?? "" };
+    }
+
+    if (msgType === "session.editor_context.update") {
+      return {
+        targetId: asString(raw.targetId) ?? asString(raw.target_id) ?? "",
+        documentEmpty: raw.documentEmpty ?? raw.document_empty ?? false,
+        insertionMode: raw.insertionMode ?? raw.insertion_mode ?? "append",
+        leftContext: raw.leftContext ?? raw.left_context ?? "",
+        rightContext: raw.rightContext ?? raw.right_context ?? "",
+        selectedText: raw.selectedText ?? raw.selected_text,
+        cursorOffset: raw.cursorOffset ?? raw.cursor_offset,
+      };
+    }
+
+    return raw;
+  }
+
+  private _attachRoomListeners(_params: TransportConnectParams): void {
+    if (!this.room) return;
+
+    this.room.on(RoomEvent.ConnectionStateChanged, (lkState) => {
+      dbgRawEvent("livekit", "RoomEvent.ConnectionStateChanged", { state: lkState });
+      switch (lkState) {
+        case ConnectionState.Connected:
+          this._setState({ status: "connected" });
+          break;
+        case ConnectionState.Disconnected:
+          this._setState({ status: "disconnected" });
+          break;
+        case ConnectionState.Reconnecting:
+          this._setState({
+            status: "reconnecting",
+            reconnectCount: this._state.reconnectCount + 1,
+          });
+          break;
+      }
+      dbgState("livekit.transport", this._state);
+    });
+
+    this.room.on(RoomEvent.Reconnecting, () => {
+      dbgRawEvent("livekit", "RoomEvent.Reconnecting", {});
+      this._setState({
+        status: "reconnecting",
+        reconnectCount: this._state.reconnectCount + 1,
+      });
+      dbgState("livekit.transport", this._state);
+    });
+
+    this.room.on(RoomEvent.Reconnected, () => {
+      dbgRawEvent("livekit", "RoomEvent.Reconnected", {});
+      this._setState({ status: "reconnected" });
+      dbgState("livekit.transport", this._state);
+    });
+
+    this.room.on(RoomEvent.ConnectionQualityChanged, (quality) => {
+      dbgRawEvent("livekit", "RoomEvent.ConnectionQualityChanged", { quality });
+      const mapped =
+        quality === ConnectionQuality.Excellent ? "excellent" :
+        quality === ConnectionQuality.Good ? "good" :
+        quality === ConnectionQuality.Poor ? "poor" : "unknown";
+      this._setState({ connectionQuality: mapped });
+      dbgState("livekit.transport", this._state);
+    });
+
+    this.room.on(RoomEvent.LocalTrackPublished, () => {
+      dbgRawEvent("livekit", "RoomEvent.LocalTrackPublished", {});
+      this._setState({ localAudioPublished: true });
+      dbgState("livekit.transport", this._state);
+    });
+
+    this.room.on(RoomEvent.LocalTrackUnpublished, () => {
+      dbgRawEvent("livekit", "RoomEvent.LocalTrackUnpublished", {});
+      this._setState({ localAudioPublished: false });
+      dbgState("livekit.transport", this._state);
+    });
+
+    this.room.on(RoomEvent.LocalAudioSilenceDetected, () => {
+      dbgRawEvent("livekit", "RoomEvent.LocalAudioSilenceDetected", {});
+      this._setState({ localAudioMuted: true });
+      dbgState("livekit.transport", this._state);
+    });
+
+    this.room.on(RoomEvent.MediaDevicesError, (err) => {
+      dbgRawEvent("livekit", "RoomEvent.MediaDevicesError", { error: err instanceof Error ? err.message : String(err) });
+      const failure = MediaDeviceFailure.getFailure(err);
+      switch (failure) {
+        case MediaDeviceFailure.PermissionDenied:
+          this._emitError("audio.permission_denied", "Autorisation micro refusée — vérifier les paramètres du navigateur");
+          break;
+        case MediaDeviceFailure.NotFound:
+          this._emitError("audio.no_input_device", "Aucun microphone détecté");
+          break;
+        case MediaDeviceFailure.DeviceInUse:
+          this._emitError("audio.device_in_use", "Micro occupé par une autre application");
+          break;
+        default:
+          this._emitError("audio.no_input_device", err instanceof Error ? err.message : String(err));
+      }
+    });
+
+    // Écoute le topic serveur unique du wire V2.
+    this.room.on(RoomEvent.DataReceived, (payload, _participant, kind, topic) => {
+      const isReliable = kind === DataPacket_Kind.RELIABLE;
+      const isLossy = kind === DataPacket_Kind.LOSSY;
+
+      if (topic !== TOPIC_SERVER_EVENT) return;
+      if (!isReliable && !isLossy) return;
+
+      try {
+        const data = JSON.parse(textDecoder.decode(payload)) as Record<string, unknown>;
+        dbgRawEvent("livekit", "RoomEvent.DataReceived", { topic, kind, data });
+        const parsed = ephiaWireServerEventSchema.safeParse(data);
+        if (!parsed.success) {
+          console.warn("[LiveKitTransport] invalid server event schema (ignored):", parsed.error.issues);
+          return;
+        }
+        this._handleWireServerEvent(parsed.data);
+      } catch (err) {
+        console.warn("[LiveKitTransport] failed to parse data channel payload", err);
+      }
+    });
+  }
+
+  private _handleWireServerEvent(event: EphiaServerEvent): void {
+    this._serverEventCallbacks.forEach((cb) => cb(event));
+  }
+
+  private _roomOptions() {
+    return {
+      adaptiveStream: false,
+      dynacast: false,
+      disconnectOnPageLeave: false,
+      reconnectPolicy: RECONNECT_POLICY,
+      audioCaptureDefaults: {
+        echoCancellation: true,
+        noiseSuppression: true,
+        autoGainControl: true,
+      },
+    };
+  }
+
+  private _setState(partial: Partial<TransportState>): void {
+    const next = { ...this._state, ...partial };
+    let changed = false;
+    for (const key in partial) {
+      if ((next as any)[key] !== (this._state as any)[key]) {
+        changed = true;
+        break;
+      }
+    }
+    if (!changed) return;
+    this._state = next;
+    this._stateCallbacks.forEach((cb) => cb(this._state));
+  }
+
+  private _emitError(code: EphiaSdkError["code"], message: string): void {
+    const err = new EphiaSdkError(code, message);
+    this._errorCallbacks.forEach((cb) => cb(err));
+  }
+}

package/src/core/transport/MockTransport.ts

@@ -0,0 +1,231 @@
+/**
+ * Transport mock pour tests, storybook et sandbox sans backend.
+ */
+
+import type { EphiaAudioEvent, EphiaClientMessage, EphiaServerEvent } from "ephia-protocol";
+import { PROTOCOL_VERSION, ephiaAudioEventSchema } from "ephia-protocol";
+import { EphiaSdkError } from "../../shared/errors/EphiaSdkError";
+import type {
+  Transport,
+  TransportConnectParams,
+  TransportState,
+} from "./Transport";
+
+function uuid(): string {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+type MockScriptStep = {
+  type: string;
+  delayMs: number;
+  payload?: Record<string, unknown>;
+};
+
+type MockTransportOptions = {
+  script?: MockScriptStep[];
+  autoEmitReady?: boolean;
+  latencyMs?: number;
+};
+
+export class MockTransport implements Transport {
+  private _state: TransportState = {
+    status: "idle",
+    localAudioPublished: false,
+    localAudioMuted: false,
+    reconnectCount: 0,
+  };
+
+  private _eventCallbacks: Array<(event: EphiaAudioEvent) => void> = [];
+  private _serverEventCallbacks: Array<(event: EphiaServerEvent) => void> = [];
+  private _stateCallbacks: Array<(state: TransportState) => void> = [];
+  private _errorCallbacks: Array<(error: EphiaSdkError) => void> = [];
+  private _running = false;
+  private _scriptTimer: ReturnType<typeof setTimeout> | null = null;
+  private _options: MockTransportOptions;
+
+  constructor(options: MockTransportOptions = {}) {
+    this._options = options;
+  }
+
+  async connect(params: TransportConnectParams): Promise<void> {
+    this._running = true;
+    this._setState({ status: "connecting", roomName: params.roomName });
+
+    await this._delay(this._options.latencyMs ?? 100);
+
+    if (!this._running) return;
+
+    this._setState({ status: "connected" });
+
+    if (this._options.autoEmitReady !== false) {
+      this._emit({
+        protocolVersion: PROTOCOL_VERSION,
+        eventId: "00000000-0000-4000-8000-000000000001",
+        sessionId: "mock-session",
+        type: "session.ready",
+        seq: 0,
+        timestampMs: Date.now(),
+        payload: { roomName: params.roomName },
+      });
+    }
+
+    this._runScript();
+  }
+
+  async disconnect(_reason?: string): Promise<void> {
+    this._running = false;
+    if (this._scriptTimer) {
+      clearTimeout(this._scriptTimer);
+      this._scriptTimer = null;
+    }
+    this._setState({ status: "disconnected" });
+  }
+
+  async publishAudio(_track: MediaStreamTrack): Promise<void> {
+    this._setState({ localAudioPublished: true });
+  }
+
+  async unpublishAudio(): Promise<void> {
+    this._setState({ localAudioPublished: false });
+  }
+
+  async sendMessage(message: EphiaClientMessage): Promise<void> {
+    if (message.type === "session.stop") {
+      this._emit({
+        protocolVersion: PROTOCOL_VERSION,
+        eventId: "00000000-0000-4000-8000-000000000002",
+        sessionId: "mock-session",
+        type: "session.closed",
+        seq: 999,
+        timestampMs: Date.now(),
+        payload: { reason: "user_stop" },
+      });
+    }
+  }
+
+  onEvent(callback: (event: EphiaAudioEvent) => void): () => void {
+    this._eventCallbacks.push(callback);
+    return () => {
+      this._eventCallbacks = this._eventCallbacks.filter((c) => c !== callback);
+    };
+  }
+
+  onServerEvent(callback: (event: EphiaServerEvent) => void): () => void {
+    this._serverEventCallbacks.push(callback);
+    return () => {
+      this._serverEventCallbacks = this._serverEventCallbacks.filter((c) => c !== callback);
+    };
+  }
+
+  onTransportState(callback: (state: TransportState) => void): () => void {
+    this._stateCallbacks.push(callback);
+    return () => {
+      this._stateCallbacks = this._stateCallbacks.filter((c) => c !== callback);
+    };
+  }
+
+  onError(callback: (error: EphiaSdkError) => void): () => void {
+    this._errorCallbacks.push(callback);
+    return () => {
+      this._errorCallbacks = this._errorCallbacks.filter((c) => c !== callback);
+    };
+  }
+
+  getState(): TransportState {
+    return { ...this._state };
+  }
+
+  async prepareConnection(_url: string, _token?: string): Promise<void> {
+    // no-op in mock
+  }
+
+  async performRpc(method: string, payload: unknown, _timeout?: number): Promise<string> {
+    if (method === "ephia.session.sync") {
+      const lastSeq = Number((payload as { lastSeq?: number } | undefined)?.lastSeq ?? 0);
+      return JSON.stringify({
+        status: "ok",
+        mode: "replay",
+        fromSeq: lastSeq,
+        toSeq: lastSeq,
+        events: [],
+      });
+    }
+    // Délègue vers sendMessage pour que les sous-classes de test (PauseAckTransport, etc.)
+    // puissent continuer à intercepter via sendMessage sans modification.
+    const msgType = method.replace("ephia.", "") as EphiaClientMessage["type"];
+    await this.sendMessage({ type: msgType, payload: payload as any } as EphiaClientMessage);
+    return JSON.stringify({ status: "ok" });
+  }
+
+  /** Émet manuellement un event legacy (utile pour les tests). */
+  simulateEvent(event: EphiaAudioEvent): void {
+    this._emit(event);
+  }
+
+  /** Émet manuellement un event serveur V2 (utile pour les tests de TranscriptApplier). */
+  simulateServerEvent(event: EphiaServerEvent): void {
+    this._serverEventCallbacks.forEach((cb) => cb(event));
+  }
+
+  /** Force manuellement un état transport (utile pour les tests). */
+  simulateState(state: Partial<TransportState>): void {
+    this._setState(state);
+  }
+
+  // ------------------------------------------------------------------
+  // Internals
+  // ------------------------------------------------------------------
+
+  private _setState(partial: Partial<TransportState>): void {
+    this._state = { ...this._state, ...partial };
+    this._stateCallbacks.forEach((cb) => cb(this._state));
+  }
+
+  private _emit(event: EphiaAudioEvent): void {
+    const parsed = ephiaAudioEventSchema.safeParse(event);
+    if (!parsed.success) {
+      console.warn(
+        "[MockTransport] invalid event schema (ignored):",
+        parsed.error.issues
+      );
+      return;
+    }
+    this._eventCallbacks.forEach((cb) => cb(parsed.data));
+  }
+
+  private async _delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  private _runScript(): void {
+    const script = this._options.script ?? [];
+    let index = 0;
+
+    const runNext = () => {
+      if (!this._running || index >= script.length) return;
+      const step = script[index];
+      index++;
+
+      this._scriptTimer = setTimeout(() => {
+        if (!this._running) return;
+
+        const baseEvent: EphiaAudioEvent = {
+          protocolVersion: PROTOCOL_VERSION,
+          eventId: `00000000-0000-4000-8000-${String(index).padStart(12, "0")}`,
+          sessionId: "mock-session",
+          type: step.type as any,
+          seq: index,
+          timestampMs: Date.now(),
+          payload: (step.payload ?? {}) as any,
+        };
+
+        this._emit(baseEvent);
+        runNext();
+      }, step.delayMs);
+    };
+
+    runNext();
+  }
+}