smartkvm/ts/smartkvm.interfaces.ts

export type TKvmKind = 'jetkvm' | 'glinet' | 'pikvm' | 'tinypilot' | 'generic';

export type TKvmFrameMimeType = 'image/png' | 'image/jpeg';

export type TKvmOsHint = 'windows' | 'macos' | 'linux' | 'unknown';

export type TKvmShellHint = 'powershell' | 'cmd' | 'bash' | 'zsh' | 'sh' | 'unknown';

export type TKvmKey =
  | 'Enter'
  | 'Escape'
  | 'Tab'
  | 'Backspace'
  | 'Delete'
  | 'ArrowUp'
  | 'ArrowDown'
  | 'ArrowLeft'
  | 'ArrowRight'
  | 'Home'
  | 'End'
  | 'PageUp'
  | 'PageDown'
  | 'Space'
  | 'Meta'
  | 'Control'
  | 'Alt'
  | 'Shift'
  | 'F1'
  | 'F2'
  | 'F3'
  | 'F4'
  | 'F5'
  | 'F6'
  | 'F7'
  | 'F8'
  | 'F9'
  | 'F10'
  | 'F11'
  | 'F12'
  | string;

export interface IKvmFrame {
  timestamp: number;
  width: number;
  height: number;
  mimeType: TKvmFrameMimeType;
  dataBase64: string;
}

export interface IBrowserKvmOptions {
  url: string;
  kind?: TKvmKind;
  username?: string;
  password?: string;
  headless?: boolean;
  /**
   * Main element that should receive keyboard focus.
   * Usually video, canvas, or a wrapper around the KVM viewer.
   */
  viewerSelector?: string;
  /**
   * Element used for frame capture.
   * Defaults to video, then canvas, then viewer screenshot fallback.
   */
  captureSelector?: string;
  /**
   * Useful for self-signed KVM certificates.
   */
  ignoreHttpsErrors?: boolean;
  /**
   * Persist browser session cookies/login state.
   */
  userDataDir?: string;
  /**
   * Optional browser executable path.
   */
  executablePath?: string;
  /**
   * Optional timeout for initial load and viewer detection.
   */
  timeoutMs?: number;
}

export interface IKvmTypeTextOptions {
  delayMs?: number;
}

export interface IKvmDriver {
  readonly kind: TKvmKind;
  connect: () => Promise<void>;
  disconnect: () => Promise<void>;
  focusViewer: () => Promise<void>;
  captureFrame: () => Promise<IKvmFrame>;
  typeText: (text: string, options?: IKvmTypeTextOptions) => Promise<void>;
  pressKey: (key: TKvmKey) => Promise<void>;
  pressShortcut: (keys: TKvmKey[]) => Promise<void>;
  wait: (milliseconds: number) => Promise<void>;
}

export interface IOcrCrop {
  x: number;
  y: number;
  width: number;
  height: number;
}

export interface IOcrRecognizeOptions {
  crop?: IOcrCrop;
  language?: string;
}

export interface IOcrResult {
  text: string;
  confidence?: number;
}

export interface IOcrEngine {
  recognize: (frame: IKvmFrame, options?: IOcrRecognizeOptions) => Promise<IOcrResult>;
}

export interface IKvmTerminalOptions {
  kvm: IKvmDriver;
  ocrEngine: IOcrEngine;
  osHint?: TKvmOsHint;
  shellHint?: TKvmShellHint;
  commandTimeoutMs?: number;
  ocrPollIntervalMs?: number;
  ocrMaxAttempts?: number;
  /**
   * Optional OCR crop to limit recognition to terminal area.
   */
  ocrCrop?: IOcrCrop;
}

export interface IKvmTerminalCommandResult {
  commandId: string;
  command: string;
  completed: boolean;
  timedOut: boolean;
  exitCode?: number;
  combinedText: string;
  rawOcrText: string;
}

export interface IWrappedKvmCommand {
  commandId: string;
  shellHint: TKvmShellHint;
  command: string;
  textToType: string;
  startMarker: string;
  endMarkerPrefix: string;
}