@ephia/dova-sdk 1.0.0

package/src/devices/speechmike/speechmike-button-router.ts

@@ -0,0 +1,73 @@
+import { DEFAULT_BUTTON_MAPPING, SPEECHMIKE_CONFIG } from "./constants";
+import type { DictationSupportEnum } from "./dictation-support-loader";
+import type { EphiaSpeechMikeAction } from "./types";
+
+export type ButtonRouterEvent = {
+  buttons: Set<string>;
+  actions: EphiaSpeechMikeAction[];
+  rawBitMask: number;
+};
+
+export class SpeechMikeButtonRouter {
+  private lastEventTime = 0;
+  private readonly processedEvents = new Set<string>();
+  private mapping: Record<string, EphiaSpeechMikeAction>;
+
+  constructor(
+    private readonly buttonEnum: DictationSupportEnum,
+    mapping: Partial<Record<string, EphiaSpeechMikeAction>> = {},
+    private readonly debounceMs = SPEECHMIKE_CONFIG.BUTTON_DEBOUNCE_MS,
+  ) {
+    this.mapping = mergeButtonMapping(mapping);
+  }
+
+  setMapping(mapping: Partial<Record<string, EphiaSpeechMikeAction>>): void {
+    this.mapping = mergeButtonMapping(mapping);
+  }
+
+  parse(bitMask: number): ButtonRouterEvent | null {
+    const now = Date.now();
+    const buttons = new Set<string>();
+
+    for (const value of Object.values(this.buttonEnum)) {
+      const numeric = Number(value);
+      if (Number.isNaN(numeric)) continue;
+
+      if (bitMask & numeric) {
+        const name = this.buttonEnum[numeric];
+        if (name) buttons.add(name);
+      }
+    }
+
+    if (buttons.size === 0) {
+      return { buttons, actions: [], rawBitMask: bitMask };
+    }
+
+    if (now - this.lastEventTime < this.debounceMs) return null;
+
+    const eventKey = `${[...buttons].join(",")}_${Math.floor(now / this.debounceMs)}`;
+    if (this.processedEvents.has(eventKey)) return null;
+
+    this.processedEvents.add(eventKey);
+    if (typeof window !== "undefined") {
+      window.setTimeout(() => this.processedEvents.delete(eventKey), 1000);
+    }
+    this.lastEventTime = now;
+
+    const actions = [...buttons]
+      .map((button) => this.mapping[button] ?? "none")
+      .filter((action): action is Exclude<EphiaSpeechMikeAction, "none"> => action !== "none");
+
+    return { buttons, actions, rawBitMask: bitMask };
+  }
+}
+
+function mergeButtonMapping(
+  mapping: Partial<Record<string, EphiaSpeechMikeAction>>,
+): Record<string, EphiaSpeechMikeAction> {
+  const merged: Record<string, EphiaSpeechMikeAction> = { ...DEFAULT_BUTTON_MAPPING };
+  for (const [button, action] of Object.entries(mapping)) {
+    if (action !== undefined) merged[button] = action;
+  }
+  return merged;
+}

package/src/devices/speechmike/speechmike-device-manager.ts

@@ -0,0 +1,461 @@
+import {
+  getNavigatorHid,
+  matchesSpeechMikeIdentity,
+  withTimeout,
+  type HidConnectionEventLike,
+  type HidDeviceLike,
+} from "./browser";
+import { SPEECHMIKE_CONFIG } from "./constants";
+import {
+  loadDictationSupport,
+  type DictationButtonCallback,
+  type DictationDevice,
+  type DictationDeviceCallback,
+  type DictationDeviceManagerLike,
+  type DictationMotionCallback,
+  type DictationSupportRuntime,
+} from "./dictation-support-loader";
+import { SpeechMikeButtonRouter, type ButtonRouterEvent } from "./speechmike-button-router";
+import type {
+  EphiaSpeechMikeAction,
+  EphiaSpeechMikeDeviceInfo,
+  EphiaSpeechMikeError,
+  EphiaSpeechMikeHidStatus,
+} from "./types";
+
+export type SpeechMikeDeviceManagerEvents = {
+  status: (status: EphiaSpeechMikeHidStatus) => void;
+  device: (device: unknown | null) => void;
+  deviceInfo: (info: EphiaSpeechMikeDeviceInfo | null) => void;
+  presence: (present: boolean) => void;
+  button: (event: ButtonRouterEvent) => void;
+  error: (error: EphiaSpeechMikeError) => void;
+};
+
+export type SpeechMikeDeviceManagerOptions = {
+  buttonMapping?: Partial<Record<string, EphiaSpeechMikeAction>>;
+  loadRuntime?: () => Promise<DictationSupportRuntime>;
+};
+
+type EventListenerMap = {
+  [K in keyof SpeechMikeDeviceManagerEvents]: Set<SpeechMikeDeviceManagerEvents[K]>;
+};
+
+type DeviceWithHid = {
+  hidDevice?: HidDeviceLike;
+};
+
+function toError(error: unknown, fallbackCode: string): EphiaSpeechMikeError {
+  if (error && typeof error === "object" && "code" in error) {
+    const code = String((error as { code?: unknown }).code ?? fallbackCode);
+    const message = error instanceof Error ? error.message : String(error);
+    return { code, message };
+  }
+
+  return {
+    code: fallbackCode,
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+function toRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : null;
+}
+
+function getDeviceHidDevice(device: unknown): HidDeviceLike | null {
+  const maybeDevice = toRecord(device) as DeviceWithHid | null;
+  return maybeDevice?.hidDevice ?? null;
+}
+
+function sameHidDevice(a: HidDeviceLike | null | undefined, b: HidDeviceLike | null | undefined): boolean {
+  if (!a || !b) return false;
+  return a === b;
+}
+
+function extractDeviceInfo(value: unknown): EphiaSpeechMikeDeviceInfo | null {
+  const record = toRecord(value);
+  if (!record) return null;
+
+  const productName = typeof record.productName === "string" ? record.productName : undefined;
+  const manufacturerName =
+    typeof record.manufacturerName === "string" ? record.manufacturerName : undefined;
+  const vendorId = typeof record.vendorId === "number" ? record.vendorId : undefined;
+  const productId = typeof record.productId === "number" ? record.productId : undefined;
+
+  if (
+    productName === undefined &&
+    manufacturerName === undefined &&
+    vendorId === undefined &&
+    productId === undefined
+  ) {
+    return null;
+  }
+
+  return { productName, manufacturerName, vendorId, productId };
+}
+
+export class SpeechMikeDeviceManager {
+  private readonly listeners: EventListenerMap = {
+    status: new Set(),
+    device: new Set(),
+    deviceInfo: new Set(),
+    presence: new Set(),
+    button: new Set(),
+    error: new Set(),
+  };
+
+  private readonly loadRuntime: () => Promise<DictationSupportRuntime>;
+  private readonly initialButtonMapping: Partial<Record<string, EphiaSpeechMikeAction>>;
+  private manager: DictationDeviceManagerLike | null = null;
+  private router: SpeechMikeButtonRouter | null = null;
+  private currentDevice: DictationDevice | null = null;
+  private currentDeviceInfo: EphiaSpeechMikeDeviceInfo | null = null;
+  private status: EphiaSpeechMikeHidStatus = "idle";
+  private physicallyPresent = false;
+  private initialized = false;
+  private disposed = false;
+  private reconnectLock = false;
+  private watchdogInterval: number | null = null;
+
+  private readonly onButtonEvent: DictationButtonCallback = (_device, bitMask) => {
+    const event = this.router?.parse(bitMask);
+    if (event) this.emit("button", event);
+  };
+
+  private readonly onDeviceConnected: DictationDeviceCallback = (device) => {
+    void this.attachDevice(device, "sdk-connect");
+  };
+
+  private readonly onDeviceDisconnected: DictationDeviceCallback = () => {
+    this.detachDevice("sdk-disconnect");
+  };
+
+  private readonly onMotionEvent: DictationMotionCallback = () => {};
+
+  private readonly onHidConnect = (event: Event) => {
+    void this.handleHidConnect(event as HidConnectionEventLike);
+  };
+
+  private readonly onHidDisconnect = (event: Event) => {
+    void this.handleHidDisconnect(event as HidConnectionEventLike);
+  };
+
+  constructor(options: SpeechMikeDeviceManagerOptions = {}) {
+    this.loadRuntime = options.loadRuntime ?? loadDictationSupport;
+    this.initialButtonMapping = options.buttonMapping ?? {};
+  }
+
+  async initialize(): Promise<void> {
+    if (this.disposed) return;
+    if (this.initialized) return;
+    this.initialized = true;
+
+    const hid = getNavigatorHid();
+    if (!hid) {
+      this.setStatus("unsupported");
+      return;
+    }
+
+    this.setStatus("initializing");
+
+    try {
+      const runtime = await this.loadRuntime();
+      if (this.disposed) return;
+
+      this.router = new SpeechMikeButtonRouter(runtime.ButtonEvent, this.initialButtonMapping);
+      const manager = new runtime.DictationDeviceManager();
+      this.manager = manager;
+
+      manager.addButtonEventListener?.(this.onButtonEvent);
+      manager.addDeviceConnectedEventListener?.(this.onDeviceConnected);
+      manager.addDeviceDisconnectedEventListener?.(this.onDeviceDisconnected);
+      manager.addMotionEventListener?.(this.onMotionEvent);
+
+      hid.addEventListener("connect", this.onHidConnect);
+      hid.addEventListener("disconnect", this.onHidDisconnect);
+
+      if (manager.init) {
+        await withTimeout(
+          manager.init(),
+          SPEECHMIKE_CONFIG.DEVICE_OPERATION_TIMEOUT_MS,
+          "speechmike.init",
+        );
+      }
+
+      await this.reconnect();
+      this.startWatchdog();
+    } catch (error) {
+      const err = toError(error, "speechmike.initialize_failed");
+      this.emit("error", err);
+      this.setStatus(err.code === "speechmike.driver_missing" ? "driver_missing" : "error");
+    }
+  }
+
+  async requestAuthorization(): Promise<void> {
+    await this.initialize();
+    if (this.disposed) return;
+    if (!this.manager) {
+      const error = {
+        code: "speechmike.manager_unavailable",
+        message: "SpeechMike manager is not initialized",
+      };
+      this.emit("error", error);
+      throw new Error(error.message);
+    }
+
+    this.setStatus("authorization_required");
+
+    try {
+      await withTimeout(
+        this.manager.requestDevice(),
+        SPEECHMIKE_CONFIG.REQUEST_DEVICE_TIMEOUT_MS,
+        "speechmike.requestDevice",
+      );
+      const device = this.getManagerDevices()[0] ?? null;
+      if (!device) {
+        this.setStatus("error");
+        throw new Error("No SpeechMike device returned after authorization");
+      }
+      await this.attachDevice(device, "user-grant");
+    } catch (error) {
+      const err = toError(error, "speechmike.authorization_failed");
+      this.emit("error", err);
+      this.setStatus("present_unauthorized");
+      throw error;
+    }
+  }
+
+  async reconnect(): Promise<void> {
+    if (this.reconnectLock || this.disposed) return;
+    this.reconnectLock = true;
+    this.setStatus(this.currentDevice ? "recovering" : "restoring");
+
+    try {
+      const device = this.getManagerDevices()[0] ?? null;
+      if (device) {
+        await this.attachDevice(device, "reconnect");
+        return;
+      }
+
+      const present = await this.detectPhysicalPresence();
+      this.setPhysicallyPresent(present);
+      this.detachDevice(present ? "present-unauthorized" : "not-present", {
+        status: present ? "present_unauthorized" : "not_present",
+      });
+    } catch (error) {
+      const err = toError(error, "speechmike.reconnect_failed");
+      this.emit("error", err);
+      this.setStatus("error");
+    } finally {
+      this.reconnectLock = false;
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    if (this.watchdogInterval !== null && typeof window !== "undefined") {
+      window.clearInterval(this.watchdogInterval);
+      this.watchdogInterval = null;
+    }
+
+    const hid = getNavigatorHid();
+    hid?.removeEventListener("connect", this.onHidConnect);
+    hid?.removeEventListener("disconnect", this.onHidDisconnect);
+
+    this.manager?.removeButtonEventListener?.(this.onButtonEvent);
+    this.manager?.removeDeviceConnectedEventListener?.(this.onDeviceConnected);
+    this.manager?.removeDeviceDisconnectedEventListener?.(this.onDeviceDisconnected);
+    this.manager?.removeMotionEventListener?.(this.onMotionEvent);
+    this.manager?.disconnect?.();
+
+    this.currentDevice = null;
+    this.currentDeviceInfo = null;
+    this.manager = null;
+    this.router = null;
+    this.initialized = false;
+    this.emit("device", null);
+    this.emit("deviceInfo", null);
+  }
+
+  getCurrentDevice(): unknown | null {
+    return this.currentDevice;
+  }
+
+  getStatus(): EphiaSpeechMikeHidStatus {
+    return this.status;
+  }
+
+  getPhysicallyPresent(): boolean {
+    return this.physicallyPresent;
+  }
+
+  getDeviceInfo(): EphiaSpeechMikeDeviceInfo | null {
+    return this.currentDeviceInfo;
+  }
+
+  setButtonMapping(mapping: Partial<Record<string, EphiaSpeechMikeAction>>): void {
+    this.router?.setMapping(mapping);
+  }
+
+  on<K extends keyof SpeechMikeDeviceManagerEvents>(
+    event: K,
+    cb: SpeechMikeDeviceManagerEvents[K],
+  ): () => void {
+    this.listeners[event].add(cb);
+    return () => {
+      this.listeners[event].delete(cb);
+    };
+  }
+
+  private async attachDevice(device: DictationDevice, _cause: string): Promise<void> {
+    if (this.disposed) return;
+
+    this.currentDevice = device;
+    this.setPhysicallyPresent(true);
+    this.currentDeviceInfo = await this.resolveDeviceInfo(device);
+    this.emit("device", device);
+    this.emit("deviceInfo", this.currentDeviceInfo);
+    this.setStatus("connected");
+  }
+
+  private detachDevice(
+    _cause: string,
+    options: { status?: EphiaSpeechMikeHidStatus } = {},
+  ): void {
+    this.currentDevice = null;
+    this.currentDeviceInfo = null;
+    this.emit("device", null);
+    this.emit("deviceInfo", null);
+    this.setStatus(options.status ?? "disconnected");
+  }
+
+  private async handleHidConnect(event: HidConnectionEventLike): Promise<void> {
+    if (this.disposed) return;
+    const present = await this.detectPhysicalPresence();
+    this.setPhysicallyPresent(present);
+    if (!present) return;
+
+    const devices = this.getManagerDevices();
+    const connectedHidDevice = event.device;
+    const match =
+      devices.find((device) => sameHidDevice(getDeviceHidDevice(device), connectedHidDevice)) ??
+      devices[0] ??
+      null;
+
+    if (match) {
+      await this.attachDevice(match, "hid-connect");
+    } else {
+      this.setStatus("present_unauthorized");
+    }
+  }
+
+  private async handleHidDisconnect(event: HidConnectionEventLike): Promise<void> {
+    if (this.disposed) return;
+    const currentHidDevice = getDeviceHidDevice(this.currentDevice);
+    if (sameHidDevice(currentHidDevice, event.device)) {
+      this.detachDevice("hid-disconnect");
+    }
+    this.setPhysicallyPresent(await this.detectPhysicalPresence());
+  }
+
+  private startWatchdog(): void {
+    if (this.watchdogInterval !== null || typeof window === "undefined") return;
+    this.watchdogInterval = window.setInterval(() => {
+      void this.watchdogTick();
+    }, SPEECHMIKE_CONFIG.WATCHDOG_INTERVAL_MS);
+  }
+
+  private async watchdogTick(): Promise<void> {
+    if (this.reconnectLock || this.disposed) return;
+    this.reconnectLock = true;
+
+    try {
+      const present = await this.detectPhysicalPresence();
+      this.setPhysicallyPresent(present);
+
+      if (!this.currentDevice && present) {
+        const device = this.getManagerDevices()[0] ?? null;
+        if (device) {
+          await this.attachDevice(device, "watchdog-restore");
+        } else {
+          this.setStatus("present_unauthorized");
+        }
+      } else if (this.currentDevice && !present) {
+        this.detachDevice("watchdog-absent", { status: "disconnected" });
+      }
+    } finally {
+      this.reconnectLock = false;
+    }
+  }
+
+  private async detectPhysicalPresence(): Promise<boolean> {
+    const hid = getNavigatorHid();
+    if (hid) {
+      try {
+        const devices = await hid.getDevices();
+        if (devices.some(matchesSpeechMikeIdentity)) return true;
+      } catch {
+        // Fall through to MediaDevices.
+      }
+    }
+
+    try {
+      const devices = await navigator.mediaDevices?.enumerateDevices?.();
+      return !!devices?.some((device) => {
+        const label = (device.label ?? "").toLowerCase();
+        return (
+          device.kind === "audioinput" &&
+          (label.includes("speechmike") ||
+            label.includes("philips") ||
+            label.includes("dictation"))
+        );
+      });
+    } catch {
+      return false;
+    }
+  }
+
+  private async resolveDeviceInfo(
+    device: DictationDevice,
+  ): Promise<EphiaSpeechMikeDeviceInfo | null> {
+    const fromDevice = extractDeviceInfo(device);
+    if (fromDevice) return fromDevice;
+
+    const hidDevice = getDeviceHidDevice(device);
+    const fromHid = extractDeviceInfo(hidDevice);
+    if (fromHid) return fromHid;
+
+    try {
+      const info = await this.manager?.getDeviceInfo?.(device);
+      return extractDeviceInfo(info);
+    } catch {
+      return null;
+    }
+  }
+
+  private getManagerDevices(): DictationDevice[] {
+    const devices = this.manager?.getDevices?.() ?? [];
+    return Array.isArray(devices) ? devices : [];
+  }
+
+  private setStatus(status: EphiaSpeechMikeHidStatus): void {
+    if (this.status === status) return;
+    this.status = status;
+    this.emit("status", status);
+  }
+
+  private setPhysicallyPresent(present: boolean): void {
+    if (this.physicallyPresent === present) return;
+    this.physicallyPresent = present;
+    this.emit("presence", present);
+  }
+
+  private emit<K extends keyof SpeechMikeDeviceManagerEvents>(
+    event: K,
+    payload: Parameters<SpeechMikeDeviceManagerEvents[K]>[0],
+  ): void {
+    for (const listener of this.listeners[event]) {
+      (listener as (value: typeof payload) => void)(payload);
+    }
+  }
+}

package/src/devices/speechmike/speechmike-led-controller.ts

@@ -0,0 +1,78 @@
+import { DEFAULT_LED_INTENTS, SPEECHMIKE_CONFIG } from "./constants";
+import { withTimeout } from "./browser";
+import type { EphiaSpeechMikeLedIntent } from "./types";
+
+type LedCapableDevice = {
+  setLed?: (index: number, mode: number) => Promise<void>;
+  setLeds?: (states: Record<number, number>) => Promise<void>;
+};
+
+function isLedCapableDevice(device: unknown): device is LedCapableDevice {
+  if (!device || typeof device !== "object") return false;
+  return "setLed" in device || "setLeds" in device;
+}
+
+export class SpeechMikeLedController {
+  private queue: Promise<void> = Promise.resolve();
+
+  constructor(private readonly getDevice: () => unknown | null) {}
+
+  setIntent(intent: EphiaSpeechMikeLedIntent): void {
+    this.setBatchQueued(DEFAULT_LED_INTENTS[intent]);
+  }
+
+  setBatchQueued(states: Record<number, number>): void {
+    this.queue = this.queue
+      .catch(() => undefined)
+      .then(() => this.setBatch(states))
+      .catch(() => undefined);
+  }
+
+  async setBatch(states: Record<number, number>): Promise<void> {
+    const device = this.getLedDevice();
+    if (!device) return;
+
+    if (typeof device.setLeds === "function") {
+      try {
+        await withTimeout(
+          device.setLeds(states),
+          SPEECHMIKE_CONFIG.LED_OPERATION_TIMEOUT_MS,
+          "setLeds",
+        );
+        return;
+      } catch {
+        // Fall back to individual LED calls.
+      }
+    }
+
+    await Promise.allSettled(
+      Object.entries(states).map(([index, mode]) => this.setLed(Number(index), mode)),
+    );
+  }
+
+  async setLed(index: number, mode: number): Promise<boolean> {
+    const device = this.getLedDevice();
+    if (!device?.setLed) return false;
+
+    try {
+      await withTimeout(
+        device.setLed(index, mode),
+        SPEECHMIKE_CONFIG.LED_OPERATION_TIMEOUT_MS,
+        `setLed(${index})`,
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  clear(): void {
+    this.setIntent("off");
+  }
+
+  private getLedDevice(): LedCapableDevice | null {
+    const device = this.getDevice();
+    return isLedCapableDevice(device) ? device : null;
+  }
+}
+

package/src/devices/speechmike/types.ts

@@ -0,0 +1,96 @@
+export type EphiaSpeechMikeHidStatus =
+  | "unsupported"
+  | "driver_missing"
+  | "idle"
+  | "initializing"
+  | "not_present"
+  | "present_unauthorized"
+  | "authorization_required"
+  | "restoring"
+  | "connected"
+  | "disconnected"
+  | "recovering"
+  | "error";
+
+export type EphiaSpeechMikeAudioStatus =
+  | "idle"
+  | "permission_required"
+  | "resolving"
+  | "ready"
+  | "not_found"
+  | "error";
+
+export interface EphiaSpeechMikeStatus {
+  hid: EphiaSpeechMikeHidStatus;
+  audio: EphiaSpeechMikeAudioStatus;
+}
+
+export type EphiaSpeechMikeButton =
+  | "RECORD"
+  | "PLAY"
+  | "FORWARD"
+  | "REWIND"
+  | "F1"
+  | "F1_A"
+  | "F2"
+  | "F2_B"
+  | "F3"
+  | "F3_C"
+  | "F4"
+  | "F4_D"
+  | "INS"
+  | "OVR"
+  | "INS_OVR"
+  | "EOL"
+  | "EOL_PRIO"
+  | string;
+
+export type EphiaSpeechMikeAction =
+  | "record.toggle"
+  | "record.start"
+  | "record.stop"
+  | "play.toggle"
+  | "seek.forward"
+  | "seek.backward"
+  | "audio.submit"
+  | "audio.discard"
+  | "agent.open"
+  | "exam.new"
+  | "resources.toggle"
+  | "none";
+
+export type EphiaSpeechMikeLedIntent =
+  | "off"
+  | "idle"
+  | "recording"
+  | "processing"
+  | "audio_available"
+  | "success"
+  | "error"
+  | "cancelled";
+
+export interface EphiaSpeechMikeDeviceInfo {
+  productName?: string;
+  manufacturerName?: string;
+  vendorId?: number;
+  productId?: number;
+}
+
+export interface EphiaSpeechMikeError {
+  code: string;
+  message: string;
+}
+
+export interface EphiaSpeechMikeState {
+  status: EphiaSpeechMikeStatus;
+  device: unknown | null;
+  deviceInfo: EphiaSpeechMikeDeviceInfo | null;
+  physicallyPresent: boolean;
+  audioInputDeviceId: string | null;
+  audioInputDeviceLabel: string | null;
+  pressedButtons: Set<string>;
+  lastButton: string | null;
+  lastAction: EphiaSpeechMikeAction | null;
+  error: EphiaSpeechMikeError | null;
+}
+