@ephia/dova-sdk 1.0.0

package/src/core/client/EphiaAudioClient.ts

@@ -0,0 +1,654 @@
+/**
+ * EphiaAudioClient — façade publique vers le nouvel agent ephia-transcribe-agent.
+ *
+ * Architecture simplifiée : SessionApiClient + AudioCaptureManager + Transport direct.
+ * Pas d'EventGate / CatchupCoordinator / SessionSyncService / ReconnectionManager.
+ */
+
+import type { EphiaClientMessage, EphiaServerEvent } from "ephia-protocol";
+import type { Transport, TransportState } from "../transport/Transport";
+import { LiveKitTransport } from "../transport/LiveKitTransport";
+import type { EphiaClientState } from "./client-state";
+import { initialClientState } from "./client-state";
+import { canTransition, transitionSessionStatus } from "../session/session-machine";
+import type { EphiaSessionStatus } from "../session/session-machine";
+import { EphiaSdkError } from "../../shared/errors/EphiaSdkError";
+import { dbgState } from "../../debug/sdk-debug-collector";
+import { SDK_VERSION, PROTOCOL_VERSION } from "./constants";
+import type { EphiaAudioClientOptions, EphiaStartOptions, EphiaStartResult } from "./client-options";
+export type { EphiaAudioClientOptions, EphiaStartOptions, EphiaStartResult } from "./client-options";
+export { SDK_VERSION, PROTOCOL_VERSION } from "./constants";
+import { SessionApiClient } from "./session-api";
+import { AudioCaptureManager } from "./audio-capture";
+
+export class EphiaAudioClient {
+  private options: EphiaAudioClientOptions;
+  private transport: Transport;
+  private state: EphiaClientState = { ...initialClientState };
+  private _unbindTransport?: () => void;
+
+  private _stopping = false;
+  private _intentionalDisconnect = false;
+  private _startAbortController: AbortController | null = null;
+  private _lastConnectParams: { livekitUrl: string; token: string; roomName: string; sessionId: string } | null = null;
+  private _tokenRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+  private _serverSessionClosed = false;
+
+  private readonly sessionApi: SessionApiClient;
+  private readonly audio: AudioCaptureManager;
+
+  constructor(options: EphiaAudioClientOptions = {}) {
+    this.options = options;
+    this.transport = options.transport ?? new LiveKitTransport();
+
+    this.sessionApi = new SessionApiClient({
+      apiUrl: options.apiUrl,
+      apiKey: options.apiKey,
+      bearerToken: options.bearerToken,
+      clientType: options.clientType,
+      sessionOptions: options.sessionOptions,
+      isIdle: () => this.state.status === "idle",
+      onPrepareConnection: (url, token) => {
+        this.transport.prepareConnection?.(url, token).catch(() => {});
+      },
+      onPreloadComplete: () => {
+        this._emitSdkDebug("sdk.preload.done", { ts: Date.now() });
+      },
+      onPreloadFailed: () => {
+        this._emitSdkDebug("sdk.preload.failed", { ts: Date.now() });
+      },
+    });
+
+    this.audio = new AudioCaptureManager({
+      onAudioState: (s) => this.options.onAudioState?.(s),
+      getLocalAudioPublished: () => this.state.isMicEnabled,
+    });
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────────────
+
+  async preload(signal?: AbortSignal): Promise<void>;
+  async preload(options?: EphiaStartOptions, signal?: AbortSignal): Promise<void>;
+  async preload(
+    optionsOrSignal?: EphiaStartOptions | AbortSignal,
+    maybeSignal?: AbortSignal
+  ): Promise<void> {
+    if (this.state.status !== "idle") return;
+    if (optionsOrSignal && "aborted" in optionsOrSignal) {
+      return this.sessionApi.preload(optionsOrSignal);
+    }
+    return this.sessionApi.preload(optionsOrSignal, maybeSignal);
+  }
+
+  releasePreloadedSession(): void {
+    this.sessionApi.cancelTimers();
+    const orphaned = this.sessionApi.discardPreloadedSession();
+    if (orphaned) {
+      this.sessionApi.stopBackendSession(orphaned.sessionId).catch(() => {});
+    }
+  }
+
+  async warmupMic(): Promise<void> {
+    return this.audio.warmupMic();
+  }
+
+  injectWarmupStream(stream: MediaStream): void {
+    this.audio.injectWarmupStream(stream);
+  }
+
+  async start(options?: EphiaStartOptions): Promise<EphiaStartResult> {
+    if (this.state.status === "ended" || this.state.status === "error") {
+      this._resetForStart();
+    }
+
+    // Resume from paused (room still connected, just republish audio)
+    if (this.state.status === "paused" && this._hasReusableRoom()) {
+      await this._resumeAudio(options);
+      return { sessionId: this.state.sessionId };
+    }
+
+    if (!canTransition(this.state.status, "creating_session")) {
+      throw new EphiaSdkError(
+        "client.invalid_state",
+        `Cannot start while status is ${this.state.status}`
+      );
+    }
+
+    this._setStatus("creating_session");
+    this._startAbortController = new AbortController();
+    const { signal } = this._startAbortController;
+
+    let acquiredStream: MediaStream | undefined;
+    let sessionData: Awaited<ReturnType<SessionApiClient["createSession"]>> | undefined;
+
+    try {
+      // Acquire mic + session in parallel
+      const micPromise = this.audio
+        .acquireMicStream(this.options.preferredAudioInputDeviceId)
+        .then((stream) => {
+          if (!signal.aborted) {
+            acquiredStream = stream;
+            this.audio.setActiveStream(stream);
+          } else {
+            stream.getTracks().forEach((t) => t.stop());
+          }
+        });
+
+      let sessionPromise: Promise<void>;
+      const preloaded = this.sessionApi.takePreloadedSession();
+      if (preloaded) {
+        sessionData = preloaded;
+        this.state = { ...this.state, sessionId: preloaded.sessionId, roomName: preloaded.roomName };
+        this.options.onStateChange?.(this.getState());
+        sessionPromise = Promise.resolve();
+      } else {
+        if (this.sessionApi.hasPreloadInFlight()) {
+          await this.sessionApi.awaitPreloadIfPending(signal);
+          const fromFlight = this.sessionApi.takePreloadedSession();
+          if (fromFlight) {
+            sessionData = fromFlight;
+            this.state = { ...this.state, sessionId: fromFlight.sessionId, roomName: fromFlight.roomName };
+            this.options.onStateChange?.(this.getState());
+            sessionPromise = Promise.resolve();
+          } else {
+            sessionPromise = this.sessionApi.createSessionWithRetry(signal, options).then((data) => {
+              if (!signal.aborted) {
+                sessionData = data;
+                this.state = { ...this.state, sessionId: data.sessionId, roomName: data.roomName };
+                this.options.onStateChange?.(this.getState());
+              }
+            });
+          }
+        } else {
+          sessionPromise = this.sessionApi.createSessionWithRetry(signal, options).then((data) => {
+            if (!signal.aborted) {
+              sessionData = data;
+              this.state = { ...this.state, sessionId: data.sessionId, roomName: data.roomName };
+              this.options.onStateChange?.(this.getState());
+            }
+          });
+        }
+      }
+
+      await Promise.all([micPromise, sessionPromise]);
+
+      if (signal.aborted) {
+        this._handleStartAborted();
+        return { sessionId: null };
+      }
+      if (!acquiredStream || !sessionData) {
+        throw new EphiaSdkError("client.start_failed", "Missing stream or session");
+      }
+
+      // Connect transport
+      this._setStatus("connecting_transport");
+      this._unbindTransport?.();
+      this._unbindTransport = this._bindTransportEvents();
+
+      const connectParams = {
+        livekitUrl: sessionData.livekitUrl,
+        token: sessionData.token,
+        roomName: sessionData.roomName,
+        sessionId: sessionData.sessionId,
+      };
+      this._lastConnectParams = connectParams;
+      this._scheduleTokenRefresh(sessionData.sessionId);
+      await this._connectTransportWithRetry(connectParams, signal);
+      await this._sendInitialTargetBeforeAudio(options?.initialTargetId, signal);
+
+      if (signal.aborted) {
+        await this._disconnectTransport().catch(() => {});
+        this._handleStartAborted();
+        return { sessionId: null };
+      }
+
+      // Publish audio
+      this._setStatus("ready");
+      const track = acquiredStream.getAudioTracks()[0];
+      if (!track) {
+        throw new EphiaSdkError("audio.no_input_device", "No audio track");
+      }
+      if (!track.enabled) track.enabled = true;
+
+      try {
+        await this.transport.publishAudio(track, { enableNoiseFilter: this.options.noiseFilter });
+      } catch (err) {
+        if (err instanceof EphiaSdkError) throw err;
+        const message = err instanceof Error ? err.message : String(err);
+        throw new EphiaSdkError("audio.track_publish_failed", message);
+      }
+
+      if (signal.aborted) {
+        await this.transport.unpublishAudio().catch(() => {});
+        await this._disconnectTransport().catch(() => {});
+        this._handleStartAborted();
+        return { sessionId: null };
+      }
+
+      this._setStatus("recording");
+      this.state = { ...this.state, isMicEnabled: true };
+      this.options.onStateChange?.(this.getState());
+      await this.audio.setupAudioLevel(acquiredStream);
+
+      this._emitSdkDebug("sdk.record.started", { sessionId: sessionData.sessionId, ts: Date.now() });
+
+      return { sessionId: sessionData.sessionId };
+    } catch (err) {
+      if (signal.aborted) {
+        await this._disconnectTransport().catch(() => {});
+        this._handleStartAborted();
+        return { sessionId: null };
+      }
+      const code = err instanceof EphiaSdkError ? err.code : "client.start_failed";
+      const message = err instanceof Error ? err.message : String(err);
+      this._setErrorState(code, message);
+      this.audio.cleanupActiveStream();
+      await this._disconnectTransport().catch(() => {});
+      throw err;
+    } finally {
+      if (this._startAbortController?.signal === signal) {
+        this._startAbortController = null;
+      }
+    }
+  }
+
+  /** Arrête l'enregistrement sans fermer la room (reprise possible via start()). */
+  async stop(): Promise<void> {
+    if (this._stopping) return;
+    this.audio.stopAudioLevelImmediately?.();
+
+    if (this._startAbortController) {
+      this._stopping = true;
+      this._startAbortController.abort();
+      this._startAbortController = null;
+      this._handleStartAborted();
+      this._stopping = false;
+      return;
+    }
+
+    if (
+      this.state.status === "idle" ||
+      this.state.status === "paused" ||
+      this.state.status === "ended" ||
+      this.state.status === "error" ||
+      this.state.status === "disposed"
+    ) {
+      return;
+    }
+
+    if (
+      this.state.status === "creating_session" ||
+      this.state.status === "connecting_transport"
+    ) {
+      this._stopping = true;
+      await this._disconnectTransport().catch(() => {});
+      this._handleStartAborted();
+      this._stopping = false;
+      return;
+    }
+
+    this._stopping = true;
+    try {
+      await this.transport.unpublishAudio().catch(() => {});
+      this.audio.cleanupActiveStream();
+      this.state = { ...this.state, isMicEnabled: false };
+      this._setStatus("paused");
+      this.options.onStateChange?.(this.getState());
+    } finally {
+      this._stopping = false;
+    }
+  }
+
+  /** Termine complètement la session : déconnecte la room et stop le backend. */
+  async endSession(): Promise<void> {
+    if (this._stopping) return;
+    this.audio.stopAudioLevelImmediately?.();
+
+    if (this._startAbortController) {
+      this._stopping = true;
+      this._startAbortController.abort();
+      this._startAbortController = null;
+      this._handleStartAborted();
+      this._stopping = false;
+      return;
+    }
+
+    if (
+      this.state.status === "idle" ||
+      this.state.status === "ended" ||
+      this.state.status === "disposed"
+    ) {
+      return;
+    }
+
+    this._stopping = true;
+    const sessionId = this.state.sessionId;
+    try {
+      await this.transport.unpublishAudio().catch(() => {});
+      this.audio.cleanupActiveStream();
+      this._intentionalDisconnect = true;
+      await this._disconnectTransport().catch(() => {});
+      if (sessionId) {
+        this.sessionApi.stopBackendSession(sessionId).catch(() => {});
+      }
+      this._markSessionEnded();
+    } finally {
+      this._intentionalDisconnect = false;
+      this._stopping = false;
+    }
+  }
+
+  registerPageHideStop(): () => void {
+    if (typeof window === "undefined") return () => {};
+    const handler = () => {
+      const sessionId = this.state.sessionId;
+      if (sessionId) this.sessionApi.stopBackendSessionOnPageHide(sessionId);
+    };
+    window.addEventListener("pagehide", handler);
+    return () => window.removeEventListener("pagehide", handler);
+  }
+
+  async dispose(): Promise<void> {
+    if (this._startAbortController) {
+      this._startAbortController.abort();
+      this._startAbortController = null;
+      this._handleStartAborted();
+      return;
+    }
+    const status = this.state.status;
+    if (status === "recording" || status === "ready") {
+      await this.endSession();
+      return;
+    }
+    this.sessionApi.cancelTimers();
+    const orphaned = this.sessionApi.discardPreloadedSession();
+    if (orphaned) this.sessionApi.stopBackendSession(orphaned.sessionId).catch(() => {});
+    this._intentionalDisconnect = true;
+    await this._disconnectTransport().catch(() => {});
+    this._intentionalDisconnect = false;
+    this._unbindTransport?.();
+    this._unbindTransport = undefined;
+    this.audio.cleanupActiveStream();
+    this.audio.cleanupWarmupStream?.();
+    this.state = { ...this.state, status: "disposed" };
+    this.options.onStateChange?.(this.getState());
+  }
+
+  getState(): EphiaClientState {
+    return { ...this.state };
+  }
+
+  setPreferredAudioInputDeviceId(deviceId: string | undefined): void {
+    this.options = { ...this.options, preferredAudioInputDeviceId: deviceId };
+  }
+
+  onTransportState(callback: (state: TransportState) => void): () => void {
+    return this.transport.onTransportState(callback);
+  }
+
+  onServerEvent(callback: (event: EphiaServerEvent) => void): () => void {
+    return this.transport.onServerEvent(callback);
+  }
+
+  async sendMessage(message: EphiaClientMessage): Promise<void> {
+    await this.transport.sendMessage(message);
+  }
+
+  async getAvailableMicrophones(): Promise<MediaDeviceInfo[]> {
+    return this.audio.getAvailableMicrophones();
+  }
+
+  async switchMicrophone(deviceId: string): Promise<void> {
+    await this.transport.switchActiveDevice?.("audioinput", deviceId);
+  }
+
+  exportTrace(): Record<string, unknown> {
+    return {
+      sdkVersion: SDK_VERSION,
+      protocolVersion: PROTOCOL_VERSION,
+      sessionId: this.state.sessionId,
+      state: this.state,
+    };
+  }
+
+  getDebugSnapshot(): Record<string, unknown> {
+    return {
+      sdkVersion: SDK_VERSION,
+      protocolVersion: PROTOCOL_VERSION,
+      state: this.state,
+      lastAudioState: this.audio.lastAudioState,
+      stopping: this._stopping,
+      intentionalDisconnect: this._intentionalDisconnect,
+      preloadedSession: this.sessionApi.preloadedSession,
+      lastConnectParams: this._lastConnectParams
+        ? { ...this._lastConnectParams, token: "[redacted]" }
+        : null,
+      hasActiveStream: this.audio.hasActiveStream,
+    };
+  }
+
+  // ── Internals ────────────────────────────────────────────────────────────────
+
+  private _bindTransportEvents(): () => void {
+    const unsubServerEvent = this.transport.onServerEvent((event) => {
+      if (event.type === "session.error") {
+        this._setErrorState(event.payload.code, event.payload.message);
+        this._serverSessionClosed = true;
+      }
+      if (event.type === "session.status") {
+        if (event.payload.status === "closed") {
+          this._serverSessionClosed = true;
+        } else if (event.payload.status === "ready") {
+          this._serverSessionClosed = false;
+        }
+      }
+    });
+
+    const unsubState = this.transport.onTransportState((tState) => {
+      if (tState.status === "disconnected" && !this._intentionalDisconnect && !this._stopping) {
+        // LiveKit exhausted its reconnect retries
+        this._setErrorState("transport.disconnected", "Connexion perdue");
+      }
+    });
+
+    const unsubError = this.transport.onError((err) => {
+      this._setErrorState(err.code, err.message);
+    });
+
+    return () => {
+      unsubServerEvent();
+      unsubState();
+      unsubError();
+    };
+  }
+
+  private async _resumeAudio(options?: EphiaStartOptions): Promise<void> {
+    if (this.state.isMicEnabled) return;
+    try {
+      const stream = await this.audio.acquireMicStream(this.options.preferredAudioInputDeviceId);
+      if (!stream) throw new EphiaSdkError("audio.no_input_device", "No mic stream");
+      this.audio.setActiveStream(stream);
+      const track = stream.getAudioTracks()[0];
+      if (!track) throw new EphiaSdkError("audio.no_input_device", "No audio track");
+      await this._sendInitialTargetBeforeAudio(options?.initialTargetId);
+      try {
+        await this.transport.publishAudio(track, { enableNoiseFilter: this.options.noiseFilter });
+      } catch (err) {
+        if (err instanceof EphiaSdkError) throw err;
+        const message = err instanceof Error ? err.message : String(err);
+        throw new EphiaSdkError("audio.track_publish_failed", message);
+      }
+      await this.transport.sendMessage({
+        type: "session.resume",
+        payload: {
+          context: options?.context,
+        },
+      });
+      this._setStatus("recording");
+      this.state = { ...this.state, isMicEnabled: true };
+      this.options.onStateChange?.(this.getState());
+      await this.audio.setupAudioLevel(stream);
+    } catch (err) {
+      const code = err instanceof EphiaSdkError ? err.code : "client.start_failed";
+      const message = err instanceof Error ? err.message : String(err);
+      this._setErrorState(code, message);
+      this.audio.cleanupActiveStream();
+      throw err;
+    }
+  }
+
+  private _hasReusableRoom(): boolean {
+    const status = this.transport.getState().status;
+    return (
+      !!this.state.sessionId &&
+      (status === "connected" || status === "reconnected")
+    );
+  }
+
+  private _handleStartAborted(): void {
+    this.audio.cleanupActiveStream();
+    const orphaned = this.sessionApi.discardPreloadedSession();
+    if (orphaned) this.sessionApi.stopBackendSession(orphaned.sessionId).catch(() => {});
+    this._forceIdle();
+  }
+
+  private _forceIdle(): void {
+    this.state = { ...this.state, status: "idle", isMicEnabled: false };
+    this.options.onStateChange?.(this.getState());
+  }
+
+  private _resetForStart(): void {
+    this._unbindTransport?.();
+    this._unbindTransport = undefined;
+    this.audio.cleanupActiveStream();
+    const orphaned = this.sessionApi.discardPreloadedSession();
+    if (orphaned) this.sessionApi.stopBackendSession(orphaned.sessionId).catch(() => {});
+    this.sessionApi.cancelTimers();
+    if (this._tokenRefreshTimer !== null) {
+      clearTimeout(this._tokenRefreshTimer);
+      this._tokenRefreshTimer = null;
+    }
+    this._lastConnectParams = null;
+    this.state = {
+      ...this.state,
+      status: "idle",
+      sessionId: null,
+      roomName: null,
+      error: null,
+      isMicEnabled: false,
+    };
+  }
+
+  private _markSessionEnded(): void {
+    this._unbindTransport?.();
+    this._unbindTransport = undefined;
+    if (this._tokenRefreshTimer !== null) {
+      clearTimeout(this._tokenRefreshTimer);
+      this._tokenRefreshTimer = null;
+    }
+    this._lastConnectParams = null;
+    if (
+      this.state.status !== "ended" &&
+      this.state.status !== "error" &&
+      this.state.status !== "disposed"
+    ) {
+      this._setStatus("ended");
+    }
+    this.state = { ...this.state, isMicEnabled: false };
+    this.options.onStateChange?.(this.getState());
+  }
+
+  private _setStatus(next: EphiaSessionStatus): void {
+    const current = this.state.status;
+    if (current === next) return;
+    const status = transitionSessionStatus(current, next);
+    this.state = { ...this.state, status };
+    dbgState("sdk.client", this.getDebugSnapshot());
+    this.options.onStateChange?.(this.getState());
+  }
+
+  private _setErrorState(code: string, message: string): void {
+    const error = { code, message };
+    const current = this.state.status;
+    if (canTransition(current, "error")) {
+      this._setStatus("error");
+    } else {
+      this.state = { ...this.state, status: "error" };
+    }
+    this.state = { ...this.state, error, isMicEnabled: false };
+    this.options.onStateChange?.(this.getState());
+    this.options.onError?.(error);
+  }
+
+  private _scheduleTokenRefresh(sessionId: string): void {
+    if (this._tokenRefreshTimer !== null) clearTimeout(this._tokenRefreshTimer);
+    this._tokenRefreshTimer = setTimeout(() => {
+      this._tokenRefreshTimer = null;
+      if (!this._lastConnectParams) return;
+      void this.sessionApi.refreshToken(sessionId).then((token) => {
+        if (token && this._lastConnectParams) {
+          this._lastConnectParams = { ...this._lastConnectParams, token };
+        }
+      });
+    }, this.sessionApi.activeTokenRefreshDelayMs);
+  }
+
+  private async _connectTransportWithRetry(
+    params: { livekitUrl: string; token: string; roomName: string; sessionId: string },
+    signal?: AbortSignal
+  ): Promise<void> {
+    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 {
+        await this.transport.connect(params as any);
+        return;
+      } catch (err) {
+        lastErr = err;
+        if (err instanceof EphiaSdkError) throw err;
+        if (signal?.aborted) throw err;
+        if (attempt < maxRetries) {
+          const delay = 300 * Math.pow(2, attempt) + Math.random() * 100;
+          await new Promise<void>((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    throw lastErr;
+  }
+
+  private async _sendInitialTargetBeforeAudio(
+    targetId?: string,
+    signal?: AbortSignal
+  ): Promise<void> {
+    if (!targetId) return;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (signal?.aborted) throw new EphiaSdkError("client.start_failed", "Start aborted");
+      try {
+        await this.transport.sendMessage({
+          type: "session.target.changed",
+          payload: { targetId },
+        } as unknown as EphiaClientMessage);
+        return;
+      } catch (err) {
+        if (attempt === 2) throw err;
+        await new Promise<void>((resolve) => setTimeout(resolve, 50 * (attempt + 1)));
+      }
+    }
+  }
+
+  private async _disconnectTransport(): Promise<void> {
+    this._unbindTransport?.();
+    this._unbindTransport = undefined;
+    await this.transport.disconnect();
+  }
+
+  private _emitSdkDebug(type: string, payload: Record<string, unknown>): void {
+    if (typeof window === "undefined") return;
+    window.dispatchEvent(
+      new CustomEvent("ephia:sdk-debug", {
+        detail: { type, sessionId: this.state.sessionId ?? null, payload },
+      })
+    );
+  }
+}