@ephia/dova-sdk 1.0.0

package/src/dictation_support.d.ts

@@ -0,0 +1,31 @@
+declare module "dictation_support" {
+  export type DictationDevice = unknown;
+
+  export const ButtonEvent: Record<number, string> & Record<string, number>;
+  export const MotionEvent: (Record<number, string> & Record<string, number>) | undefined;
+
+  export class DictationDeviceManager {
+    init?: () => Promise<void>;
+    requestDevice(): Promise<DictationDevice[]>;
+    getDeviceInfo?: (device: DictationDevice) => Promise<unknown>;
+    getDevices?: () => DictationDevice[];
+    addButtonEventListener?: (
+      cb: (device: DictationDevice, bitMask: number) => void,
+    ) => void;
+    removeButtonEventListener?: (
+      cb: (device: DictationDevice, bitMask: number) => void,
+    ) => void;
+    addDeviceConnectedEventListener?: (cb: (device: DictationDevice) => void) => void;
+    removeDeviceConnectedEventListener?: (cb: (device: DictationDevice) => void) => void;
+    addDeviceDisconnectedEventListener?: (cb: (device: DictationDevice) => void) => void;
+    removeDeviceDisconnectedEventListener?: (cb: (device: DictationDevice) => void) => void;
+    addMotionEventListener?: (
+      cb: (device: DictationDevice, motion: number) => void,
+    ) => void;
+    removeMotionEventListener?: (
+      cb: (device: DictationDevice, motion: number) => void,
+    ) => void;
+    disconnect?: () => void;
+  }
+}
+

package/src/global.d.ts

@@ -0,0 +1,10 @@
+declare global {
+  interface Window {
+    /** Timestamp (Date.now()) du clic Enregistrer — utilisé pour mesurer la latence jusqu'au premier partial/final. */
+    __ephia_record_click_ts?: number;
+    /** Collecteur de debug runtime exposé par le SDK en mode dev. */
+    __ephia_sdk_debug__?: import("./debug/sdk-debug-collector").SdkDebugCollector;
+  }
+}
+
+export {};

package/src/headless/createEphiaClient.ts

@@ -0,0 +1,220 @@
+import { EphiaAudioClient } from "../core/client/EphiaAudioClient";
+import type { EphiaAudioClientOptions, EphiaStartOptions, EphiaStartResult } from "../core/client/EphiaAudioClient";
+import { TranscriptApplier } from "../core/runtime/TranscriptApplier";
+import { TargetManager } from "../core/targets/TargetManager";
+import type { EphiaBinding } from "../core/bindings/EphiaBinding";
+import type { EditorContext, EphiaServerEvent, ResetReason } from "ephia-protocol";
+import type { Transport } from "../core/transport/Transport";
+
+export type EphiaHeadlessTarget = {
+  id: string;
+  binding: EphiaBinding;
+  mode?: string;
+};
+
+export type EphiaHeadlessOptions = {
+  apiUrl?: string;
+  apiKey?: string;
+  bearerToken?: string;
+  clientType?: string;
+  language?: string;
+  /** Pre-registered targets. Additional targets can be registered via registerTarget(). */
+  targets?: EphiaHeadlessTarget[];
+  /** Single target shorthand; equivalent to targets: [{ id: "default", binding }]. */
+  binding?: EphiaBinding;
+  /** Transport override for testing. */
+  transport?: Transport;
+};
+
+export type EphiaHeadlessClient = {
+  /**
+   * Subscribe to a typed V2 server event. Returns an unsubscriber.
+   *
+   * @example
+   * const unsub = client.on("segment.operation", (event) => { ... });
+   * // later:
+   * unsub();
+   */
+  on<T extends EphiaServerEvent["type"]>(
+    type: T,
+    handler: (event: Extract<EphiaServerEvent, { type: T }>) => void,
+  ): () => void;
+
+  start(targetId?: string, options?: EphiaStartOptions): Promise<EphiaStartResult>;
+  start(options?: EphiaStartOptions): Promise<EphiaStartResult>;
+  stop(): Promise<void>;
+  pause(): Promise<void>;
+  resume(options?: EphiaStartOptions): Promise<void>;
+  endSession(): Promise<void>;
+  warmupMic(): Promise<void>;
+
+  /**
+   * Registers a new target binding. Returns an unsubscriber.
+   */
+  registerTarget(target: EphiaHeadlessTarget): () => void;
+
+  /**
+   * Notifies the backend that a specific target is now active.
+   * Sends session.target.changed + editor_context.update.
+   */
+  setActiveTarget(targetId: string): Promise<void>;
+
+  /**
+   * Sends a manual editor context snapshot to the backend.
+   * Use when the backend needs cursor/text state without a target switch.
+   */
+  sendEditorContext(context: EditorContext): Promise<void>;
+
+  /**
+   * Resets the dictation context for a specific target (clears pending segments).
+   */
+  resetTarget(targetId: string, reason?: ResetReason): Promise<void>;
+
+  /**
+   * Resets the global session context (all targets).
+   */
+  resetSession(reason?: ResetReason): Promise<void>;
+
+  dispose(): Promise<void>;
+};
+
+export function createEphiaClient(options: EphiaHeadlessOptions): EphiaHeadlessClient {
+  const audioClient = new EphiaAudioClient({
+    apiUrl: options.apiUrl,
+    apiKey: options.apiKey,
+    bearerToken: options.bearerToken,
+    clientType: options.clientType,
+    sessionOptions: options.language ? { language: options.language } : undefined,
+    transport: options.transport,
+  } as EphiaAudioClientOptions);
+
+  const targetManager = new TargetManager({
+    sendMessage: (message) => audioClient.sendMessage(message as any),
+  });
+
+  const applier = new TranscriptApplier({ targetManager });
+  const unsubServerEvent = audioClient.onServerEvent((event) => applier.handleEvent(event));
+
+  function register(target: EphiaHeadlessTarget): () => void {
+    target.binding.attach();
+    const token = targetManager.register({ id: target.id, binding: target.binding, mode: target.mode ?? "write" });
+    return () => {
+      const removed = targetManager.unregister(target.id, token);
+      if (removed) target.binding.detach();
+    };
+  }
+
+  const initialTargets = options.targets ?? [];
+  if (options.binding) {
+    initialTargets.push({ id: "default", binding: options.binding, mode: "write" });
+  }
+  const cleanupTargets = initialTargets.map(register);
+
+  async function sendWireMessage(type: string, payload?: Record<string, unknown>): Promise<void> {
+    await audioClient.sendMessage({ type, payload } as any);
+  }
+
+  return {
+    on<T extends EphiaServerEvent["type"]>(
+      type: T,
+      handler: (event: Extract<EphiaServerEvent, { type: T }>) => void,
+    ): () => void {
+      return audioClient.onServerEvent((event) => {
+        if (event.type === type) {
+          handler(event as Extract<EphiaServerEvent, { type: T }>);
+        }
+      });
+    },
+
+    async start(
+      targetIdOrOptions?: string | EphiaStartOptions,
+      maybeOptions?: EphiaStartOptions,
+    ): Promise<EphiaStartResult> {
+      const targetId =
+        typeof targetIdOrOptions === "string" ? targetIdOrOptions : undefined;
+      const startOptions =
+        typeof targetIdOrOptions === "string" ? maybeOptions : targetIdOrOptions;
+
+      if (targetId) {
+        targetManager.setActive(targetId);
+      }
+
+      const activeTargetId = targetId ?? targetManager.getActiveTargetId() ?? undefined;
+      targetManager.prepareForDictation(activeTargetId);
+
+      const result = await audioClient.start(
+        targetId ? { ...startOptions, initialTargetId: targetId } : startOptions,
+      );
+
+      // Mirror what the React hook does: resync target + editor context after start.
+      targetManager.syncActiveTarget();
+      targetManager.flushEditorContext(
+        targetId ?? targetManager.getActiveTargetId() ?? undefined,
+      );
+
+      return result;
+    },
+
+    async stop(): Promise<void> {
+      await audioClient.stop();
+    },
+
+    async pause(): Promise<void> {
+      await audioClient.stop();
+    },
+
+    async resume(resumeOptions?: EphiaStartOptions): Promise<void> {
+      const status = audioClient.getState().status;
+      if (status === "paused") {
+        targetManager.prepareForDictation(targetManager.getActiveTargetId() ?? undefined);
+        await audioClient.start(resumeOptions);
+        targetManager.syncActiveTarget();
+        targetManager.flushEditorContext(targetManager.getActiveTargetId() ?? undefined);
+      } else {
+        throw new Error("[ephia] resume() requires a paused session; call start() to create a new session");
+      }
+    },
+
+    async endSession(): Promise<void> {
+      await audioClient.endSession();
+    },
+
+    async warmupMic(): Promise<void> {
+      await audioClient.warmupMic();
+    },
+
+    registerTarget(target: EphiaHeadlessTarget): () => void {
+      return register(target);
+    },
+
+    async setActiveTarget(targetId: string): Promise<void> {
+      targetManager.setActive(targetId);
+    },
+
+    async sendEditorContext(context: EditorContext): Promise<void> {
+      await sendWireMessage("session.editor_context.update", context as unknown as Record<string, unknown>);
+    },
+
+    async resetTarget(targetId: string, reason?: ResetReason): Promise<void> {
+      await sendWireMessage("session.reset", {
+        scope: "target",
+        targetId,
+        reason: reason ?? "user_explicit",
+      });
+    },
+
+    async resetSession(reason?: ResetReason): Promise<void> {
+      await sendWireMessage("session.reset", {
+        scope: "global",
+        reason: reason ?? "user_explicit",
+      });
+    },
+
+    async dispose(): Promise<void> {
+      unsubServerEvent();
+      cleanupTargets.forEach((cleanup) => cleanup());
+      targetManager.dispose();
+      await audioClient.dispose();
+    },
+  };
+}

package/src/headless/index.ts

@@ -0,0 +1,18 @@
+export { createEphiaClient } from "./createEphiaClient";
+export type {
+  EphiaHeadlessOptions,
+  EphiaHeadlessClient,
+  EphiaHeadlessTarget,
+} from "./createEphiaClient";
+
+// Bindings V2 — exposed so headless consumers can construct their own targets.
+export type { EphiaBinding, UpsertSegmentInput, PreviewSegmentInput } from "../core/bindings/EphiaBinding";
+export { NativeBinding } from "../core/bindings/native/NativeBinding";
+export {
+  TiptapBinding,
+  EphiaV2PreviewMark,
+  EphiaV2CommittedMark,
+} from "../core/bindings/tiptap/TiptapBinding";
+
+// Protocol types commonly needed by headless integrations.
+export type { EditorContext, ResetReason, EphiaServerEvent } from "ephia-protocol";

package/src/index.ts

@@ -0,0 +1,89 @@
+// ── React public API ───────────────────────────────────────────────────────────
+export {
+  EphiaProvider,
+  EphiaAuto,
+  useEphia,
+  useEphiaStatus,
+  useOptionalEphiaStatus,
+  useEphiaError,
+  useEphiaPartial,
+  useEphiaConnection,
+  useOptionalEphiaConnection,
+  useEphiaAudioLevel,
+  useEphiaSpeaking,
+  useEphiaNativeTarget,
+  useEphiaTarget,
+  useEphiaTiptap,
+  EphiaDictationButton,
+  EphiaStatusBar,
+  EphiaTextarea,
+  EphiaSpeechMikeProvider,
+  useEphiaSpeechMike,
+} from "./react";
+
+export type {
+  EphiaProviderProps,
+  UseEphiaReturn,
+  EphiaStatus,
+  EphiaStartResult,
+  EphiaSpeechMikeAction,
+  EphiaSpeechMikeAudioStatus,
+  EphiaSpeechMikeButton,
+  EphiaSpeechMikeDeviceInfo,
+  EphiaSpeechMikeError,
+  EphiaSpeechMikeHidStatus,
+  EphiaSpeechMikeLedIntent,
+  EphiaSpeechMikeProviderProps,
+  EphiaSpeechMikeState,
+  EphiaSpeechMikeStatus,
+} from "./react";
+
+export * from "./devices/speechmike";
+
+// ── Headless public API ────────────────────────────────────────────────────────
+export {
+  createEphiaClient,
+} from "./headless";
+
+export type {
+  EphiaHeadlessOptions,
+  EphiaHeadlessClient,
+  EphiaHeadlessTarget,
+} from "./headless";
+
+// ── UI ─────────────────────────────────────────────────────────────────────────
+export {
+  Button,
+  Spinner,
+  EphiaFloatingButton,
+} from "./ui";
+
+export type {
+  ButtonProps,
+  SpinnerProps,
+  EphiaFloatingButtonProps,
+  EphiaFloatingButtonPosition,
+  EphiaFloatingButtonTheme,
+  EphiaFloatingButtonSize,
+  EphiaFloatingButtonBorderRadius,
+} from "./ui";
+
+// ── Shared essentials ──────────────────────────────────────────────────────────
+export {
+  EphiaSdkError,
+  getMessage,
+  DEFAULT_EPHIA_SDK_API_URL,
+  resolveEphiaSdkApiUrl,
+  initialAudioState,
+} from "./shared";
+
+export type {
+  EphiaSdkErrorCode,
+  EphiaLang,
+  EphiaClientConfig,
+  EphiaSessionOptionsConfig,
+  Mode,
+  EphiaSessionOptions,
+  EphiaAudioPermission,
+  EphiaAudioState,
+} from "./shared";

package/src/react/EphiaAuto.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+import React, { useEffect, useRef } from "react";
+import { useEphiaContext } from "./provider/EphiaContext";
+import { useEphiaInternal } from "./provider/EphiaInternalContext";
+import { NativeBinding } from "../core/bindings/native/NativeBinding";
+
+export interface EphiaAutoProps {
+  children: React.ReactNode;
+  /** CSS selector for target elements. Defaults to [data-ephia-target]. */
+  selector?: string;
+}
+
+/**
+ * Scans its descendants for [data-ephia-target] elements (textarea/input only)
+ * and registers them automatically as V2 NativeBinding targets.
+ *
+ * Uses a MutationObserver to handle dynamically added/removed elements.
+ *
+ * @example
+ * <EphiaProvider getToken={getToken}>
+ *   <EphiaAuto>
+ *     <textarea data-ephia-target="report" />
+ *   </EphiaAuto>
+ * </EphiaProvider>
+ */
+export function EphiaAuto({ children, selector = "[data-ephia-target]" }: EphiaAutoProps) {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const { registerTarget } = useEphiaContext();
+  const { clientEpoch } = useEphiaInternal();
+  const registerTargetRef = useRef(registerTarget);
+  registerTargetRef.current = registerTarget;
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+
+    const registered = new Map<Element, () => void>();
+
+    const tryRegister = (el: Element) => {
+      if (registered.has(el)) return;
+      if (
+        !(el instanceof HTMLTextAreaElement) &&
+        !(el instanceof HTMLInputElement)
+      ) {
+        console.warn("[ephia:auto] unsupported element type — only textarea/input supported", el);
+        return;
+      }
+      const id = el.getAttribute("data-ephia-target");
+      if (!id) return;
+
+      const mode = el.getAttribute("data-ephia-mode") ?? "write";
+      const binding = new NativeBinding(el);
+      const cleanup = registerTargetRef.current(id, binding, { mode, element: el });
+      registered.set(el, cleanup);
+    };
+
+    const tryUnregister = (el: Element) => {
+      const cleanup = registered.get(el);
+      if (cleanup) {
+        cleanup();
+        registered.delete(el);
+      }
+    };
+
+    const scan = () => {
+      const elements = Array.from(root.querySelectorAll(selector));
+      for (const el of elements) tryRegister(el);
+      for (const [el] of registered) {
+        if (!root.contains(el)) tryUnregister(el);
+      }
+    };
+
+    scan();
+
+    const observer = new MutationObserver(scan);
+    observer.observe(root, { childList: true, subtree: true });
+
+    return () => {
+      observer.disconnect();
+      for (const [, cleanup] of registered) cleanup();
+      registered.clear();
+    };
+  }, [selector, clientEpoch]);
+
+  return <div ref={rootRef}>{children}</div>;
+}

package/src/react/components/EphiaDictationButton.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import React, { useCallback, useState } from "react";
+import { useEphia } from "../hooks/useEphia";
+import type { EphiaStatus } from "../store/types";
+
+export interface EphiaDictationButtonRenderProps {
+  status: EphiaStatus;
+  isRecording: boolean;
+  toggle: () => void;
+  disabled: boolean;
+}
+
+export interface EphiaDictationButtonProps {
+  targetId?: string;
+  disabled?: boolean;
+  className?: string;
+  onError?: (error: unknown) => void;
+
+  /**
+   * Render prop — le dev fournit son propre rendu.
+   * Si absent, un bouton minimaliste est rendu.
+   *
+   * @example
+   * <EphiaDictationButton>
+   *   {({ isRecording, toggle }) => (
+   *     <MyButton onClick={toggle} variant={isRecording ? 'danger' : 'primary'} />
+   *   )}
+   * </EphiaDictationButton>
+   */
+  children?: (props: EphiaDictationButtonRenderProps) => React.ReactNode;
+}
+
+export function EphiaDictationButton({
+  targetId,
+  disabled = false,
+  className,
+  onError,
+  children,
+}: EphiaDictationButtonProps) {
+  const { status, isRecording, isProcessing, start, stop } = useEphia();
+  const [localError, setLocalError] = useState<string | null>(null);
+
+  const isDisabled = disabled || isProcessing;
+
+  const toggle = useCallback(async () => {
+    setLocalError(null);
+    try {
+      if (isRecording) {
+        await stop();
+      } else {
+        await start(targetId);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      setLocalError(message);
+      onError?.(err);
+    }
+  }, [isRecording, start, stop, targetId, onError]);
+
+  const renderProps: EphiaDictationButtonRenderProps = {
+    status,
+    isRecording,
+    toggle,
+    disabled: isDisabled,
+  };
+
+  if (children) {
+    return <>{children(renderProps)}</>;
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      disabled={isDisabled}
+      className={className}
+      aria-label={isRecording ? "Arrêter la dictée" : "Démarrer la dictée"}
+      aria-pressed={isRecording}
+      aria-busy={isProcessing}
+      data-ephia-control="true"
+      data-ephia-status={status}
+      title={localError ?? undefined}
+    >
+      {isRecording ? "⏹" : "🎤"}
+    </button>
+  );
+}

package/src/react/components/EphiaStatusBar.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import React from "react";
+import { useEphiaStatus, useEphiaPartial } from "../hooks/useEphia";
+import type { EphiaStatus } from "../store/types";
+
+export interface EphiaStatusBarRenderProps {
+  status: EphiaStatus;
+  partialText: string | null;
+}
+
+export interface EphiaStatusBarProps {
+  className?: string;
+  children?: (props: EphiaStatusBarRenderProps) => React.ReactNode;
+}
+
+export function EphiaStatusBar({
+  className,
+  children,
+}: EphiaStatusBarProps) {
+  const status = useEphiaStatus();
+  const partial = useEphiaPartial();
+
+  if (status === "idle" || status === "recording") return null;
+
+  const partialText = partial?.text ?? null;
+
+  const renderProps: EphiaStatusBarRenderProps = {
+    status,
+    partialText,
+  };
+
+  if (children) {
+    return <>{children(renderProps)}</>;
+  }
+
+  return (
+    <div
+      className={className}
+      data-ephia-control="true"
+      data-ephia-status={status}
+      role="status"
+      aria-live="polite"
+      aria-atomic="false"
+    >
+      <span data-ephia-indicator aria-hidden="true" />
+
+      {status === "processing" && (
+        <span data-ephia-state="processing" aria-label="Traitement en cours" />
+      )}
+
+      {status === "error" && (
+        <span data-ephia-state="error" role="alert">
+          Erreur de connexion
+        </span>
+      )}
+    </div>
+  );
+}